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and conditions of this agreement* If you feel you cannot 
accept these terns and conditions , you must return this pro- 
duct intact within 10 days of original purchase* 

1* LICENSE* Southwestern Data Systems hereby grants you upon 
receipt of this product s a nonexclusive , license to use the 
enclosed product subject to the terns and restrictions set 
forth in this agreement* 

2* COPYRIGHT. This software product and its documentation, 
is copyrighted by Southwestern Data Systems and the program 
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3* RESTRICTIONS ON USE AND TRANSFER* The original and any 
back-up copies of this product are intended for your personal 
use in conjunction with a single computer. You may not copy 
or otherwise reproduce this product in whole or part except 
as expressly permitted in this agreement . 


D 1 S C L A I M E R 


SOUTHWESTERN DATA SYSTEMS A® THE PROGRAM AUTHOR SHALL HAVE 
NO LIABILITY OR RESPONSIBILITY TO PURCHASER OR ANY OTHER 
PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS OR 
DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY 
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4, m ill vl IUjB 


1*1* Assembly Language Whys and Wherefores 

Some of you may ask "What is Assembly Language?” or "Why do I 
need to use Assembly Language; BASIC suits me fine," While 
we do not have the space here to do a treatise on the sub- 
ject, we will attempt to briefly answer the above questions. 

Computer languages are often referred to as "high level" or 
"low level" languages, BASIC, COBOL, FORTRAN and PASCAL are 
all high level languages. A high level language is one that 
usually uses English-like words (commands) and may go through 
several stages of interpretation or compilation before final- 
ly being placed in memory. The time this processing takes is 
the reason BASIC and other high level languages run far 
slower than an equivalent Assembly Language program. In 
addition, it normally consumes a great deal more available 
memory. 

From the ground up, your computer understands only two 
things , off and on. All of its calculations are handled as 
addition or subtraction but at tremendously high speeds. The 
only number system it comprehends is Base 2 (the Binary Sys- 
tem) where a "1" is represented by 00000001 and a "2" is 
represented by 00000010. 

The 6502 microprocessor has five 8-bit registers and one 16- 
bit register in the ALU (Arithmetic Logic Unit). All data is 
ultimately handled through these registers. Even this lowest 
of low-level code requires a program to function correctly. 
This program is hard wired within the 6502 itself. The 
microprocessor program functions in three cycles. It fetches 
an instruction from RAM memory in the computer , decodes it 
and executes it. 
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ILIN is a "Ted-based” editor-assembler® This means tha 
.le it is essentially new from the ground up, it adheres t 
. follows almost all of the conventions associated with TE 
", in terms of the command mnemonics , pseudo-ops, etc# 

original TED ASM was written by Randy Wiggington and Gar 
nnon. It has been widely distributed "under the counter 
user groups and individuals , under many names, and in 
riety of versions® Seemingly, each person added his ow 
ancements and improvements. MERLIN is no exception# Rep 
tenting a major step forward, with the addition of macr 
>abili ty , MERLIN appears on the scene now as one of t h 
5 1 advanced and sophisticated editor-assemblers for th 
le II, yet retains all of the easy-to-use features of TE 
it make it desirable to a beginner in assembly languag 
g ramming. 

;nif icant changes incorporated in MERLIN, in addition t 
:ros, include the use of the logical operators AND, OR, an 
, and the math operator for division, the ability to lis 
:h or without line numbers, and substantially faster edit 
* Similarly, the edit module now includes many additiona 
tmands to facilitate editing, and the "Read” command allow 
r Apple text file to be read into the edit buffer, thu 
'mit ting the use of source files from other assemblers 
:h as DOS Tool Kit. 
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2. SYSTEM REQUIREMENTS 


* 48K APPLE ] [ 

* 16K RAM CARD 

* 80 COLUMN BOARD (optional) 

* LOWER CASE BOARD (optional) 


2.1. Hardware Compatibility List 


* VIDEX VIDEOTERM 

* FULL-VIEW 80 - 80 COLUMN BOARD 

* M & R SUP 'R' TERMINAL 80 COLUMN BOARD 

* ALS SMARTERM 80 COLUMN BOARD 

* VISTA VISION 80 - 80 COLUMN BOARD 

* OMEGA MICROWARE RAMTEX 16 - 16K RAM BOARD 

* ANDROMEDA 16K BOARD 

* MICROSOFT 16K RAM BOARD 

* WIZARD 80 - 80 COLUMN BOARD 


NOTE: MERLIN has been tested with the cards/boards listed 
above. The author makes no guarantees with respect to the 
operation of MERLIN with any 80 column boards not listed. 
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3. BEGINNERS GUIDE TO USING MERLIN 


By T. Petersen 

Notes and demonstrations for the beginning MERLIN programmer. 


3.1. Introduction 

The purpose of this section is not to provide instruction in 
assembly language programming. Xt is to introduce MERLIN to 
programmers new to assembly language programming in general, 
and MERLIN in particular. 

Many of the MERLIN commands and functions are very similar in 
operation# This section does not attempt to present demon 
strations of each and every command option# The objective is 
to clarify and present examples of the more common opera”* 
tions, sufficient to provide a basis for further independent 
study on the part of the programmer# 

A note of clarification: 

Throughout the MERLIN manual, various uses are made of the 
terms n mode ,f and "module’ 1 * 

In this section, !S module t! refers to a distinct computer 
program component of the ME RL XN system# There are four 

MODULES : 

1. The EXECUTIVE 

2 • The EDITOR 

3# The ASSEMBLER 

4, The SYMBOL TABLE GENERATOR 

Each module is grouped under one of the two CONTROL MODES 

1) The EXECUTIVE, abbreviated EXEC and indicated by the 

'%' prompt* 

2) The EDITOR, indicated by the prompt. 
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EXECUTIVE CONTROL MODE 

Executive Module 


EDITOR. CONTROL MODE 

Editor Module 

Assembler Module 

Symbol Table Generator Module 

The term ?! mode !! may be used to indicate either the current 
control mode (as indicated by the prompt) or alternatively, 
while in control mode and subsequent to the issuance of an 
entry command, the system is said to be in ' [entry command ] 
mode/. For example , while typing in a program af ter issuing 
the ADD command, the system is said to be 'in ADD mode'. 

Terminating [entry command] mode returns the system to con"* 
trol mode. 


Programmers familiar with some assembly and higher-level 
languages will recall the necessity of formatting the input , 
i.e. labels , opcodes , operands and comments must be typed in 
specific fields or they will not be recognized by the 
assembler program. 

In MERLIN, the TABS ope rator provides a semi-automatic 
formatting feature. 

When entering programs , remember that during assembly each 
space in the source code causes a tab to the next tab field. 
As a demonstration, let's enter the following short routine. 

Steps from the very beginning : 

1. BRUN MERLIN 

2* When the '% ' prompt appears at the bottom of the EXEC 
mode menu, type 'E'. This instantly places the system in 
EDITOR control mode. 
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3. Since we are entering an entirely new program, at the V 
prompt type 'A' and press RETURN (A * ADD)* A * V 
appears one line down and to the right, and the cursor is 
automatically tabbed one space to the right of the line 
number. The '1' and all subsequent line numbers which 
appear after the RETURN key is pressed serve roughly the 
same purpose as line numbers in BASIC except that in 
assembly source code, line numbers are not referenced for 
lumps to subroutines or in GOTO— 'like statements. 

4, On line 1 , enter an (asterisk). An asterisk as the 
first character in any line is similar to a REM statement 
in BASIC - it tells the assembler that this is a remark 
line and anything after the asterisk is to be ignored. 
To confirm this, type the title 'DEMO PROGRAM V and hit 
the RETURN key. 

5 . After return, the cursor once again drops down one line, 
a ' 2 ' appears and the cursor skips a space. 

6 . Now, hit the space bar once and type "OBJ', space again, 
type '$300% and hit RETURN. Note in most cases the 
'OBJ' pseudo-op is neither required nor desirable. 

7. On line 3, perform the same sequence: space, type 'ORG' , 
space, type '$300', RETURN. 

8, On line 4, do not space once after the line number. Type 
'BELL', space, 'EQU' space, '$FBDD\ RETURN, 

9, Line 5 - Type 'START', space ' JSR' , space 'BELL', space, 

(semicolon), 'RING THE BELL', RETURN. Semicolons are 
a convention often used within command lines to mark the 
start of comments. 

10, Line 6 - 'END', space, 'RTS', RETURN. 

11* The program has been completely entered, but the system 
is still in ADD mode. To exit ADD, just press RETURN, or 
type CTRL-X, RETURN. The ' : ' prompt reappears at the 
left of the screen, indicating that the system has 
returned to control mode. 
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12. The screen should now appear like this: 


1 *DEMO PROGRAM 1 


2 


OBJ 

$300 

3 


ORG 

$300 

4 

BELL 

EQU 

$FBQD 

5 

START 

JSR 

BELL 

6 

END 

RTS 



Note that each string of 


; RING THE BELL 


characters has been moved to a 


specific field* There are four such fields , not including 
the line numbers on the left. 


FIELD #: 


One is reserved for labels. BELL , START and END are 
examples of labels. 

Two is reserved for opcodes , such as the MERLIN pseudo- 
ops OBJ, ORG and EQU, and the 6502 opcodes JSR and RTS. 

Three is for operands , such as $300, $FBDD and , in this 
case, BELL* 

Four will contain any comments. 

It should be apparent from this exercise that it is no t 
necessary to input extra spaces in the source file for 
formatting purposes. 

In summary , after the line numbers : 

1 ) Do not space for a label. Space once after a 
label (if there is no label , once af ter the line 
number) for the opcode. 

Space once after the opcode for the operand. Space 
once after the operand for the comment. If there 
is no operand, type a space and a semicolon. 
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3*3. System and Entry Commands 

MERLIN has a powerful and complex built-in editor. Complex 
in the range of operations possible but , after a little 
practice, remarkably easy to use. 

The following paragraphs contain only minor clarifications 
and brief demonstrations on the use of both sets of commands. 
All System and Entry commands are used in EDITOR Control Mode 
immediately after the prompt. 

CTRL-X, CTRL-C or a RETURN as the first character of a line 
exits the current [entry command] mode and returns the system 
to control mode when ADDing or INSERTing lines. CTRL-X or 
CTRL-C exits edit mode and returns the system to control mode 
after Editing lines. 

The other System and Entry Commands are terminated either 
automatically or by pressing RETURN. 

Inserting and deleting lines in the source code are both 
simple operations. The following example will INSERT three 
new lines between the existing lines 4 and 5. 

1 * After the prompt , type 'V (INSERT) , the number '5', 
and press RETURN. All inserted lines will precede the 
line numbers specified in the command. 

2 • Input an asterisk, and RETURN. Note that INSERT mode has 
not been exited, 

3 . Repeat step 2 . 

4 . Input one space , type 'TYA' , and RETURN. 

On the screen is the following : 

; 15 

5 * 

6 * 

7 TYA 

8 
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5. Hit RETURN and the system reverts to CONTROL mode, 

6, LIST the source code. 


:L 


1 

*DEMO 

PROGRAM 

: 1 


2 


OBJ 

$300 


3 


ORG 

$300 


4 

BELL 

EQU 

$FBDD 


5 

* 




6 

* 




7 


TYA 



8 

START 

JSR 

BELL 

;RING THE BELL 

9 

END 

RTS 




The three new lines (5,6, and 7) have been inserted, and the 
subsequent original source lines (now lines 8 and 9) have 
been renumbered. 


Using DELETE is equally easy. 

1. In control mode, input 'D5', and RETURN. Nothing new 
appears on the screen. 

2. LIST the source code. The source listing is one line 
shorter, one of the asterisk-only lines has disap- 
peared, and the subsequent lines have been renumbered. 


It is possible to delete a range of lines in one step. 

1. In control mode, input 'D5,6' and RETURN, 

2. LIST the source. 

Lines 5 and 6 from the previous example, which contained the 
remaining asterisk and the TYA opcode, have been deleted, and 
the subsequent lines renumbered. The listing appears the 
same as in the subsection on INPUT, Step 13. 
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This automatic renumbering feature makes it IMPORTANT that 
when deleting lines you remember to begin with highest line 
number and work back to the lowest. 

The Add, Insert, or Edit commands have several sub-commands 
comprised of CTRL-characters. To demonstrate, using our BELL 
routine : 

1 . After the ' prompt , enter 'E' (the EDIT command) and a 
line number ... (use '6' for this demonstration), and hit 
RETURN. One line down and to the right the specified 
line appears in its formatted state: 

6 END RTS 

and the cursor is ove r the 'E' in 'END', 

2. Type CTRL-D, The character under the cursor disappears. 
Type CTRL-D again, and a third time , 'END' has been 
deleted, and the cursor is positioned to the left of the 
opcode . 

3. Hit RETURN and LIST the program. In line 6 of the source 
code, only the line number and opcode remain. 

4. Repeat step 1 (above) . 

5. This time, type CTRL-I, Don't move the cursor with the 
space bar or arrow keys. Type the word 'END', and 
RETURN, 

6. LIST the program. Line 6 has been restored , 
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If you are editing a single line, hitting RETURN alone re* 
stores the control mode prompt • In step 1 (above), if yoi 
had specified a range of lines (ex:'E3,6') after issuing th< 
EDIT command, RETURN would have called up the next sequent ia! 
line number within the specified range* As the lines appear 
you have the options of editing using the various sub- 
commands , pressing RETURN which will call up the next line 
or exiting the EDIT mode using GTRL-C. NOTE; hitting RET 
will enter the entire line in memory, exactly as it appe. 
on the screen* 

The other sub-commands, CIRL-characters used under the E 
command, function similarly* Read the definitions in Sect 
3 and practice a few operations* 
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SYMBOL TABLE 


BELL 


START 


SYMBOL TABLE 


START 

BELL 


- ALPHABETICAL ORDER 
*$FBDD ? 

-$0300 


- NUMERICAL ORDER 
=$0300 
=$FBDD 


END 


END 


=$0303 


=$0303 


If instead of completing the above listings the system beeps 
and displays an error message, note the line number 
referenced in the message , and press RETURN until the 
"...BYTES..." message appears* Then refer back to the 
subsection on INPUT and compare the listing with step 13, 
Look especially for elements in incorrect fields. 

If all went well, to the right of the column of numbers down 
the middle of the screen as the now familiar , formatted 
source code. 

To the left of the numbers, beginning on line 5, is a series 
of numeric and alphabetic characters. This is the object 
code - the opcodes and operands assembled to their machine 
language hexadecimal equivalents. 

Left to right, the first group of characters is the routine's 
starting address in memory (see the definition of OBJ and ORG 
in the section entitled "Pseudo Opcodes - Directives"). 
After the colon is the number '20'. This is the one-byte 
hexadecimal code for the opcode JSR. 

NOTE: that the label 'START' is not assembled into object 
code; neither are comments, remarks, or pseudo-ops such as 
OBJ and ORG. Such elements are only for the convenience and 
utility of the programmer and the use of the assembler pro- 
gram* They are of no use to the computer and therefore, are 
not translated into the machine's language. 
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The next two bytes (each pair of characters is one byte) on 
line 5 bear a curious resemblance to the last group of char- 
acters on line 4; have a look. In line 4 of the source code 
we told the assembler that the label 'BELL' EQUated with 
address $FBDD. In line 5, when the assembler encountered 
"BELL' as the operand, it substituted the specified address. 
The sequence of the high and low-order bytes was reversed, a 
6502 microprocessor convention. 

The rest of the information presented should explain itself. 
The total errors encountered in the source code was zero, and 
four bytes of object code (count the bytes following the 
addresses) was generated. 


3.5, Saving and Running Programs 

The final step in using MERLIN is running the program. Be- 
fore that , it would be a good idea to save the source code, 
OBJECT CODE SAVE must be preceded by a successful assembly, 

1 • Return to control mode if necessary, and type 'Q' RETURN. 
The system has quit EDITOR mode and reverted to EXECUTIVE 
(EXEC) mode. If the MERLIN system disk is still in the 
drive, remove it and insert an initialized work disk. 

After the prompt , type 'S' (the EXEC mode SAVE SOURCE 
FILE command). The system will ask for a filename. Type 
'DEM01', RETURN. After the program has been saved, the 
prompt returns. 

2 . Type 'C' (CATALOG) and look at the disk catalog. The 
source code has been saved as a binary file t i t led 
"DEMO 1 ,S". The suffix n .S" is a f ile-lahe lling 
convention which indicates the subject file is source 
code. This suffix is automatically appended to the name 
by the 'S' (SAVE SOURCE FILE) command. 
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3 • Hit RETURN to return to EXEC mode and input '0', for 
OBJECT CODE SAVE. The object file is saved under the 
same name as was earlier specified for the source file. 
There is no danger of overwriting the source file because 
no suffix is appended to object code file names. 

While writing either file to disk, MERLIN also displays the 
address parameter, and calculates and displays the length 
parameter. It's a good practice to take note of these. 
Viewing the catalog will show that although the optional A$ 
and L$ parameters were displayed on the EXEC mode menu, they 
were not saved as part of the file names. If you'd prefer to 
have this information in the disk catalog, use the DOS RENAME 
command. Make sure no commas are included in the new file 
name . 

Return to EDITOR mode , type 'MON' , RETURN and the monitor 
prompt appears. Enter '300G', RETURN. A beep is heard. 
The demonstration program was responsible for it. It works ! 

Now you can return to the EXEC by typing CTRL-Y and hitting 
RETURN . 


3.6. Making Back-up Copies of MERLIN 

To make back-up copies of the MERLIN diskette, you should use 
the copy program provided on the original diskette. To run 
this , simply boot on the diskette, and as the drive light 
comes on, press the 'C' key on the keyboard. The program 
will verify your intention to produce a copy, and then ask 
the slot and drive values for the SINGLE DRIVE on which the 
copy is to be made. A single drive is used to assure maximum 
reliability in the copy. 

Be careful during the copy process to appropriately alternate 
the original and copy diskettes. If at any time, you make an 
error, STOP IMMEDIATELY and re-boot to start over. 
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When completed, it is highly recommended that you use ONLY 
the BACK-UP copy of MERLIN in your daily work, and keep the 
original in a safe place. The copy program will provide a 
total of 3 back-up copies, giving you a total of 4 working 
copies of the MERLIN assembler. In addition, files may be 
transferred from one diskette to another. This means that, 
damaged files on a given diskette may be replaced with a 
known "good” file from another diskette. Use the FID file 
transfer utility on your Apple System Master diskette to move 
the file from the original master diskette to the one on 
which the file was damaged. All library files, and also the 
side containing SOURCEROR.FP can be moved to any DOS 3,3 
diskette using the FID utility program. 
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4 « EXECUTIVE MOD E 

The EXECUTIVE mode is the program level provided for file 
maintenance operations such as loading or saving code or 
cataloging the disk. The following sections summarize each 
command available in this mode. 


4,1, C s CATALOG 

A x t e r showing the catalog) this command accepts any disk 
command you wish to give , using standard DOS syntax. Unlike 
the LOAD, APPEND and SAVE commands, you must type the 
suffix when referencing a source file* This facility is 
provided primarily for locking and unlocking files. Do not 
use it to load or save files. If you do not want to give a 
disk command, just hit RETURN. To cancel a partially typed 
command use CTRL—X, make sure the command is in the wrong 
syntax (type some commas) or just backspace to the beginning* 
If you type CTRL-C RETURN after "COMMAND:”, you will be 
presented with the EXEC mode prompt ”%”• You can then issue 
any EXEC command such as ts L ?f for LOAD, This permits you to 
give an EXEC mode command while the catalog is still on the 
screen* In addition, if CTRL-C is typed at the "CATALOG 
pause” point, printing of the remainder of the catalog is 
aborted . 


4*2, L : LOAD 



This is used to load a source file from disk* You will be 
asked for the name of the file® You should not append 11 *S 
since MERLIN does this automatically. If you have hit ”L” by 
mistake, just hit RETURN twice and the command will be can- 
celled without affecting any file that may be in memory. 
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After a load (or append) command, you are automatically 
placed in the editor mode, just as if you had hit ?t E ?! » The 
source will automatically be loaded to the correct address. 
Subsequent LOAD or SAVE commands will display the last used 
filename, followed by a flashing If you hit the ,f Y" 
key, the current file name will be used for the command. If 
you hit any other key (e.g, RETURN) the cursor will be placed 
on the first character of the filename, and you may type in 
the desired name. RETURN alone at this time will cancel the 
command • 


4.3. Sj SAVE 

Use this to save a source file to disk. As in the load 
command, you do not specify the suffix H .S" and you can hit 
RETURN to cancel the command, NOTE : that the address and 
length of the source file are shown on the MENU, and are for 
information only. You should not use these for saving ; the 
assembler remembers them better than you can and sends them 
to DOS automatically. As in the LOAD command above , the 
filename will be displayed and you may type "Y" to SAVE the 
same filename, or any key for a new file name. 


4.4. A: APPEND 

This loads in a specified source file and places it at the 
end of the file currently in memory. It operates in the same 
way as the load command, and does not affect the default file 
name. It does not save the appended file; you are free to do 
that if you wish. 
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4,5, Ds DRIVE 

When you hit "D", the drive used for saving and loadings will 
change from one to two or two to one. The currently selected 
drive is shown on the menu, When MERLIN is first BRUN, the 
selected drive will he the one used by the BRUN. There is no 
command to specify slot number, but this can be accomplished 
by typing "C" for CATALOG which will display the current 
disks directory. Then give the disk command "CATALOG, Sn", 
where n is the slot number. This action will catalog the 
newly specified drive. 


4.6 , E: EDITOR 

This command places you in the EDITOR/ AS SEMBLER mode. It 
automatically sets the default tabs for the editor to those 
appropriate for source files. 


4,7 * 0 : SAVE OBJECT CODE 

You are permitted to use this command only after the success- 
ful assembly of a source file. In this case you will see the 
address and length of the object code on the menu. As with 
the source address, this is given for information only* 

NOTE: that the object address shown is that of the program's 
ORG (or $8000 by default) and not that of the actual current 
location of the assembled code (which is $8000 or whatever 
OBJ you have used). When using this command, you are asked 
for a name for the object file. Unlike the source file case, 
no suffix will be appended to this name. 
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Thus you can safely use the same name as that of the source 
file (without the n .S n of course)* When this object code is 
saved to the disk its address will be the correct one, the 
one shown on the menu* When later, you BLOAD or BRUN it, it 
will go to that address, which can be anything ($300, $800, 
etc.)* There is usually no need to use an OBJ in the source 
code, unless the object code will be too long for the space 
available at $8000 and above. 


4.8. Q i QUIT 

This exits to BASIC. You may re-enter MERLIN by issuing the 
!I ASSEM H command. This re-entry will be a warm start, which 
means it will not destroy the source file currently in 
memory. This exit can be used to give disk commands, if it 
is more convenient than the one provided by "C”. 


4.9. R : READ 


This reads text files into MERLIN. They are always appended 
to the current buffer. To clear the buffer and start fresh, 
the name given will become the default filename. Appended 
reads will not do this. 


When the read is complete, you are placed in the editor. If 
the file contains lines longer than 255 characters , these 
will be divided into two or more lines by the READ routine* 
The file will be read only until it reaches HIMEM, will 
produce a memory error if it goes beyond, and only the data 
read to that point will remain. 


The READ and WRITE command will append a "T, M to the begin- 
ning of the filename you specify UNLESS you precede the 
filename with a space or any other character in the ASCII 
range of $20 to $40. This character will be ignored and not 
used by DOS in the actual filename. 
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4.10. W: WRITE 

This writes a MERLIN file into a text file instead of a 
binary file. The speed of the READ and WRITE routines is 
approximately that of a BLOAD or BS AVE. The WRITE routine 
does a VERIFY after the write. 
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5.1.2. NEW 

Deletes present source file , resets HI MEM to $8000 
and starts fresh, 

5.1.3, PR# (0-7) 

Same function as in BASIC, Mainly used for sending an 
editor or assembly listing to a printer, DO NOT use 
this to select an 80-column card. 


5.1,4, USER 

This does a JSR $3F5. (Tha t is the Applesoft ampersand 
vector location, which normally points to an RTS,) The 
designed purpose of this command is for the connection 
of user defined printer drivers . (You must be careful 
that your printer driver does not us e zero page ad- 
dresses, except the I/O pointers and $60 - $6F, because 
this is likely to interfere with MERLIN's heavy zero 
page usage). 


5,1.5, TABS 

TABS number, number, • • * <tab character> 

This sets the tabs for the editor, and has no effect on 
the assembler listing. Up to nine tabs are possible. 
The default tab character is a space, but any may be 
specified. The assembler regards the space as the only 
acceptable tab character for the separation of labels , 
opcodes , and operands. If you don't specify the tab 
character, then the last one used remains. Entering 
TABS and a carriage return will set all tabs to ze.ro* 
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5 • 1 .6 . LENgth 

This gives the length in bytes of the source file, and 
the number of bytes remaining before HIMEM (usually 
$8000 - not BASIC HIMEM), 


5*1.7* Where 
Where (line number) 

This prints in hex, the location in memory of the start 
of the specified line* Where l? 0 !? (or ?! W0 H ) will give 
the location of the end of source* 


5,1,8* MONitor 

This exits to the monitor* You may re-enter by either 
CTRL-C, CTRL-B or CTRL-Y. These re-establish the im~ 
portant zero page pointers from a save area inside 
MERLIN itself. Thus CTRL-Y will give a correct entry, 
even if you have messed up the zero page pointers while 
in the monitor. DOS is not connected when using this 
entry to the monitor. This facility is designed for 
experienced Apple programmers, and is not recommended to 
beginners. You may re-enter the editor directly with an 
0G, 

This re-entry, unlike the others, will use the zero page 
pointers at $0A - $0F instead of the ones saved upon 
exit. Therefore , you must be sure that they have not 
been altered* 
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5.1.9. TRuncON 

This sets a flag which, during LIST or PRINT, will 
terminate printing of a line upon finding a space fol- 
lowed by a semicolon. It makes reading of source files 
easier on the Apple 40 column screen. In the assembler, 
it limits printing of the object code to three bytes per 
line and has no effect on comments. 


5.1.10. TRuncOPf 

This returns to the default condition of the truncation 
flag (which also happens automatically upon entry to the 
editor from the EXEC mode or from the assembler). In 
the assembler, this directs that all object bytes be 
printed . 


5*1.11. Quit 

Exits to EXEC mode. 


5.1.12. ASM 

This passes control to the assembler, which attempts to 
assemble the source file. First, however, you are asked 
if you wish to "update the source". This is to remind 
you to change the date or identification number in your 
source file. If you answer "N" then the assembly will 
proceed. If you answer "Y", you will be presented with 
the first line in the source containing a "/" and are 
placed in EDIT mode. When you finish editing this line 
and hi t RETURN, assembly will begin. If you use the 
CTRL-C edit abort command, however, you will return to 
the EDITOR command mode , and any 1/ 0 hooks you have 
established, by PR# etc., will have been disconnected. 
This will also happen if there is no line with a 
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NOTE: By establishing a comment line with <f * /'* at 
the beginning, you have a nearly automatic method of 
keeping track of multiple versions of a program. 


5*1*13, Control-D 

During the second pass of assembly, typing a CTRL-D will 
toggle the list flag, so that listing will either stop 
or resume* This will be defeated if a LSI opcode occurs 
in the source, but another CTRL"“D will reinstate it* 


5*1,14* Delete 

Delete (line number) <range> <range list> 

Delete (range) 

Delete (range list) 

This deletes the specified lines* Since, unlike BASIC, 
the line numbers are fictitious they change with any 
insertion or deletion. Therefore, you MUST specify the 
'higher' range first! 


5,1*15* Replace 

Replace (line number ) 

Replace (range) 

This deletes the line number or range, then places you 
into INSERT mode at that location. 
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5*1*16* List 

List (line number) 

List (range) 

List (range list) 

Lists the source file with added line numbers* Control 
characters in source are shown in inverse, unless the 
listing is being sent to a printer or other nonstandard 
outport. The listing can be aborted by CTRL-C or with 
H / ff key* You may stop the listing by hitting the space 
bar and then advance a line at a time by hitting the 
space bar again* Any other key will restart it. This 
space bar pause also works during assembly and the 
symbol table print out* 


5.1.17. * (period) 

Lists starting from the beginning of the last specified 
range. For example, if you type L10 , 100 then lines 10 
to 100 will be listed. If you then use S V ? , listing 
will start again at 10 and continue until stopped (the 
end of the range is not remembered). 


5*1*18 * / ( line number ) 

This continues listing from the last line number listed, 
or, when a line number is specified, from that line. 
This listing continues to the end of the file or until 
it is stopped as in LIST. 
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5.1*21* Find 

Find (range) 

Find (range list ) 

Find (d-string) 

This lists those xines containing the specified string* 
It may be aborted with CTRL-C or "/" key* Since the 
CTRL-L case toggle works in command mode, you can use it 
to find or change strings with lower case characters* 


5.1*22. Change 

Change ( range ) 

Change (range list ) 

Change (d-string d-string) 

This changes occurrences of the first d-string to the 
second d-string. The d-string must have the same de- 
limiter with the adjoining ones coalescing* For ex- 
ample, to change occurrences of "speling to "spelling” 
throughout the range 20,100, you would type ”€20 ,100 
speling spelling". If no range is specified, the entire 
source file is used* 

Before the change operation begins , you are asked 
whether you want to change "all" or "some". If you 
select "some" by hitting the "S" key , the editor stops 
whenever the first string is found and displays the line 
as it would appear with the change. If you then hit 
ESCAPE or any control character, the change displayed 
will not be made. Any other key, such as the space bar, 
will accept the change* CTRL-C or "/" key will abort 
the change process. 


5.1.23. COPY 

COPY (line number or range) TO (line number) 

This copies the range to just 'above' the specified 
number. It does not delete anything. 
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5*1*27* TEXT 

This converts ALL spaces in a source file to inverse 
spaces. The purpose is for use on "text 15 files so that 
it is not necessary to remember to zero the tabs before 
printing such a file. This conversion has no effect on 
anything except, the editor s tabulation* 


5,1*28* FIX 

This undoes the effect of TEXT, It also does a number 
of technical housekeeping chores* It is recommended 
that the command FIX be used on all files from external 
sources , after which the file should be saved. NOTE : 
that the TEXT and FIX routines are written in SWEET 16 
and are somewhat slow. Several minutes may be needed 
for their execution on large files, FIX or an EDIT will 
truncate any lines longer than 255 characters. 


5.1,29* SYM 

MERLIN places the symbol table on the language card (In 
bank 1 of $D000-$DFFF). This space is quite adequate 
for all but gigantic programs. In case this space is 
used up, the SYM command gives you a means to direct the 
assembler to continue the symbol table in another area* 
If you type SYM $9000, for example, and assemble the 
program, when and if the symbol table uses up its normal 
space , it will be continued at $9000 unt i 1 it reaches 
BASIC HIMEM* It must be noted that the SYM command will, 
be cancelled by a HIMEM command or by exit, to EXEC mode 
and re-entry (set HIMEM before setting up a SYM ad- 
dress.) The SYM address must be above HIMEM and below 
B ASIC H. X M. E M « I f the symbol table grows beyond the 
allotted space, you will get a memory error during the 
first pass of assembly. 
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5,1*30* VIDeo 

This command is designed to select or deselect an 80 
column board. The default condition can be selected 
using the configuration program* This is similar to the 
use of PR# in BASIC. DO NOT USE PR# to select an 80 
column board! PR# is designed for selection of a 
printer ONLY* An 80 column board in slot 3 for example, 
can be selected by typing, from the editor* VIDEO 3. 

It is deselected by VIDEO 0 or VIDEO $10 possibly fol- 
lowed by RESET. The latter two forms both select the 
standard Apple screen, but VIDEO 0 will cause all lower- 
case output to the screen to be converted to upper case 
except lower case in the source file will be converted 
to flashing upper case (output to a printer is never 
converted). If you have a lower case adapter, you will 
want to use VIDEO $10 (or VIDEO 16) instead of VIDEO 0 
when selectng the Apple screen. If your 80 column card 
has a software screen switch via an escape sequence, 
this may be used to return to 40 column mode. This will 
be equivalent to n VI D $10" and would have to be followed 
by a VID 0 if you don't have a lower case adapter. For 
example, use ESC CTRL-Q RETURN on the Smarter® or ESC-Q- 
CTRL-X on the 3up ?, R !5 term* 


5,1,31, FW (Find Word) 

FW "word" 

This is an alternative to the (F)1ND command® It will 
f ind the specified word only if it is surrounded , in 
source , by non-alpha numeric characters. Therefore , 
FW"CAT" will find: 

CAT 
CAT-1 
( CAT , X ) 

but will not find CATALOG or SCAT, 
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5.1*32. CW (Change word) 

CW 1! word ,? new stuff” 

This works as described under FW. 

5,1.33* EW (Edit word) 

EW ’’word” 

This is to EDIT as FW is to FIND. 


5*1.34. VAL 


VAL n expression” 


This will return the value of the expression as the 
assembler would compute it. 

Examples : 


VAL "LABEL" 


VAL "$1000/2" 
VAL "%1000" 

VAL ! "A" - "0"! 


gives the address (or value) 
of LABEL for the last assem- 
bly done or "unknown label" 
if not found, 
returns $0800 
returns $0008 
returns $0011 


NOTE: For the commands involving a string, the charac- 
ter acts as a "WILD CARD". Therefore, F"Jon~s" will 
find both "Jones" and "Jonas". 


38 



MERLIN Users Manual 


THE EDITOR 


5,2, Add/Insert Mode 

The ADD and INSERT modes in the editor act, as if you are in 
the mode , except that CTRL-R will do nothing, and the exit 
from ADD mode acts as described* Hitting RETURN , for 
example, will accept the entire line as shown on the screen* 


5*2*1, Add 


This places you in the ADD mode, and acts much like 
entering BASIC lines with auto line numbering* However, 
you may enter lower case text (useful for comments if 
you have a lower case adapter) by typing CTRL-L. This 
acts as a case toggle, so another CTRL-L returns you to 
UPPERCASE mode. To exit from ADD mode, hit RETURN as 
the FIRST character of a line* You. may enter an EMPTY 
line by typing a space and then RETURN. This will not 
enter the space into text , it only bypasses the exit* 
The editor automatically removes extra spaces at the end 
of lines. You may also exit the ADD mode by CTRL-X or 
CTRL-C which also cancels the current line. 


* 2 * * 

Insert (line number) 

This allows you to enter text just 'above' the specified 
line* Otherwise, it functions the same as ADD mode. 


5 , 2 # 3 , Con 1 1 o 1 L 

Toggles the current case. If you are in upper case, 
CTRL-L will place you in lower, and vice versa. Upper- 
case is defaulted to when entering each new line. 

To change the case of a word, type CTRL-L, then copy 
over the word using the right arrow. 
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5.3* Edit Mode 

After typing E in the editor, you are placed in EDIT mode. 
The first line of the range you have specified is placed on 
the screen with the cursor on. its first character. The line 
is tabbed as it is in listing, and the cursor will jump 
across the tabs as you move it with the arrow keys. When you 
are through editing, hit RETURN, 

The line will be accepted as it appears on the screen, no 
matter where the cursor is when you hit RETURN, The EDIT 
commands and functions are very similar, but not identical to 
those in Neil Konzen's Program Line Editor and Southwestern 
Data System's A.C.E. All commands except CTRL-R are avail” 
able in ADD and INSERT modes. 


5,4, Edit Mode Commands 


5,4.1, Control-I (insert) 

Begins insertion of characters. This is terminated by 
any control character except the CTRL-L case toggle , 
such as the arrows or RETURN. 


5.4.2. Control-D (delete ) 

Deletes the character under the cursor. 


5.4.3. Control-F (find) 

Finds the next occurrence of the character typed after 
the CTRL-F, This is recursive. 
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5,4,4. Control-0 (insert special) 

Functions as CTRL-I, except it inserts any control char- 
acter (including the command characters such as CTRL-Q). 


Besides enabling the insertion of control characters , 
CTRL-0 also allows the user to type characters not 
normally available on the Apple keyboard. 


Control-0 followed by: 


< 

gives 

> 

ii 

K 

5? 

L 

If 

M 

II 

N 

15 

0 

II 

k 

II 

1 

II 

m 

II 

n 

If 

o 

t! 

you are 

using a 


Control __ 
Control \ 

[ 

\ 

] 


} 

(whatever $FF gives on 
your machine) 


pending on which one you have, shift-M may give upper- 
case M and you will have to use CTRL-0 to get the right 
bracket . 


5.4.5. Control-P (do ***) 

If entered as first character of a line gives 32 *'s. 


5.4.6. Control-0 (do border) 

If entered as first character of a line gives 30 spaces 
bordered by *'s. 
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5,4*7* Gontrol-C or Control-X (cancel) 

Aborts EDIT mode and returns to the editor's warm 
start* The current line being edited will retain its 
original form* 

5*4*8, Control-B (go to line begin) 

Places the cursor at the beginning of the line. 


5.4*9, Control-N (go to line end) 

Places the cursor one space to the right of the end of 
the line. 


5.4.10. Control-R (restore line) 

Returns the line to its original form. (Not available 
in ADD and INSERT modes.) 

5.4.11. Control-Q (delete line right) 

Deletes the part of the line following the cursor. 


5,4.12, Return (RETURN key) 

Accepts the line as it appears on the screen and fetches 
the next line to be edited, or goes to the warm start if 
the specified range has been completed. 

The editor automatically replaces spaces in comments and 
ASCII strings with inverse spaces. When listing, it converts 
them hack, so you never notice this* Its purpose is to avoid 
inappropriate tabbing of comments and ASCII strings. 
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6. THE ASSEMBLER 


This section of the documentation will not attempt to teach 
you assembly language. It will only explain the syntax you 
are expected to use in your source files , and document the 
features that are available to you in the assembler. 


6.1# Number Format 

The assembler accepts decimal , hexadecimal , and binary 
numerical data. Hex numbers must be preceded by "$" and 
binary numbers by thus the following four instructions 

are all equivalent: 

LDA #100 LDA #$64 LDA #% 1100100 LDA #%01 100100 

As indicated, leading zeros are ignored. The "#" here stands 
for ’’number" or "data", and the effect of these instructions 
is to load the accumulator with the number (decimal) 100. 

A number not preceded by "#" is interpreted as an address. 
Therefore : 

<LDA 1000 LDA $3E8 LDA %1111101000> 

are equivalent ways of loading the accumulator with the byte 
that resides in memory location $3E8. 
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The assembler examines only the fir 
OPCODE (with certain exceptions such 
POPD). For example, you can use PAGE 
of the exception, the fourth lett 
however). The assembler listing will 
seven letters and will not look wel 
four unless there is no operand* 

The maximum allowable combined OPERA! 
characters* You will get an error if 
A comment line by itself is also limi 

6.3* Expressions 

To make clear the syntax accepted c 
assembler, we must define what is me 
Expressions are built up from ?s primit 
of arithmetic and logical operations, 
sions are: 

1. A label. 

2. A decimal number « 

3 ® A hexadecimal numb e r (preceded 

4. A binary number (preceded by 15 

5 . Any ASCII character preceded 
or single quotes. 

6 . The character * (standing for 

All number formats accept 16-bit date 
never required . In case 5 , the ”va 
expression is just the ASCII value < 
high-bit will be on if a quote ( M ) 
single quote ( ') is used. 
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Some examples of legal expressions are: 

LABEL I -LABEL 2 
2*LABEL+$231 
1234+% 101 1 1 
,, K ,, - t ’A ,1 +l. 

"0"! LABEL 

LABELS? $ 7 F 
*-? 

LABEL .% 10000000 

Parentheses have another meaning and are not allowed in 
expressions* All arithmetic and logical operations are done 
from left to right (2+3*5 would assemble as 25 and not 17)* 


6 • ^ ® Immediate Lata 


For those opcodes such as LDA, CMP, etc*, which accept im- 
mediate data (numbers as opposed to addresses) the immediate 
mode is signalled by preceding the expression with ! ’# , L An 
example is LDX #3* In addition: 


#<ex pression 
#>expression 
//expression 

#/ expression 


produces the low byte of the expression 
produces the high byte of the expression 
also gives the low byte (the 650 2 does 
not accept 2-byte DATA) 
is optional syntax for the high byte 
of the expression 


The ability of the assembler to evaluate expressions such as 
LAB1-LA2-1 is very useful for the following type of code: 


COMPARE 

LDX 

#F0UND-DATA-1 

LOOP 

CMP 

DA TA, X. 


BEQ 

DEX 

FOUND 


BPL 

LOOP 


JMP 

REJECT ;not found 

DATA 

HEX 

E3BC3498 

FOUND 

RTS 
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NOTE: The Accumulator mode” does not require (or accept) an 
operand* Some assemblers perversely require you to put an 
"A" in the operand for this mode. 

The assembler will decide the legality of the addressing mode 
for any given opcode* 

Additionally* MERLIN provides the ability to FORCE non-zero 
page addressing. The way to do this is to add anything 
(except "D") to the end of the opcode. Example: 

LDA $10 assembles as zero page ( 2 bytes) while , 

LDA: $10 assembles as non-zero page (3 bytes). 


6.6. Sweet 16 Opcodes 

The assembler accepts all Sweet 16 opcodes with the standard 
mnemonics. The usual Sweet 16 registers R0 to R15 do not 
have to be H equa t ed n and the n R !? is optional. TED 11+ users 
will be glad to know that the SET opcode works as it should, 
with numbers or label s . For the SET opcode , either a space 
or a comma may be used between the register and the data part 
of the operands; that is , SET R3, LABEL is equivalent to SET 
R3 LABEL, I t should be noted that the NUL opcode is 
assembled as a one-byte opcode (the same as HEX 0D) and not a 
two byte skip as this would be interpreted by ROM Sweet 16, 
This is intentional, and is done for internal reasons. 
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6*7, Pseudo Opcodes - Directives 


8*7.1. EQU ( = ) 

EQU expression (EQUals) 

« expression (optional syntax) 

Used to define the value of a LABEL, usually an exterior 
address or an often used constant for which a meaningful 
name is desired# It is recommended that these all be 
located at the beginning of the program. The assembler 
will not permit an ’’equate 11 to a zero page number after 
the label equated has been used, since bad code could 
result from such a situation (also see "Variables”). 


6 • 7 • 2« ORG 

ORG expression (ORiGin) 

Establishes the address at which the program is designed 
to run. It defaults to the present value of HIMEM 
($8000 by default ). Ordinarily there will be only one 
ORG and it will be at the start of the program. If more 
than one ORG is used, the first one establishes the 
BLOAD address. This can be used to create an object 
file that would load to one address though it may be 
designed to run at another address. 

You cannot use ORG *- 1 , etc. to back up the object 
pointers as is done in some assemblers. This must be 
done instead by DS-1. 
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6*7,3. OBJ 

OBJ expression (OBJect) 

Establishes the address at which the object code will be 
placed during assembly* It defaults to HIMEM, There is 
rarely any need to use this pseudo-op and inexperienced 
programmers are urged not to use it. An OBJ above BASIC 
HIMEM (or the SYM address , if any) will defeat genera- 
tion of object code. This may be used when sending a 
long listing to a printer or when using direct assembly 
to disk (opcode DSK). 


6,7,4* PUT 
PUT filename 

PUT FILENAME , (drive and slot parameters accepted in 
standard DOS syntax) will read the named file (with the 
”T. n prefix appended unless the filename starts with a 
character less than ”@”) and '’inserts'* it at the lo- 
cation of the opcode, 

NOTE: "Insert” refers to the effect on assembly of the 
location of the source# The file itself is actually 
placed just following the main source. Text files are 
required by this facility in order to insure memory 
protection* A memory error will occur if a PUT file 
goes beyond HIMEM, These files are in memory only one a 
time, so a very large program can be assembled using the 
PUT facility. 

There are two restrictions on a PUT file. First, there 
cannot be macro DEFINITIONS inside a PUT file, they must 
be in the main source. Second, a PUT file may not call 
another PUT file with the PUT opcode. Of course, link- 
ing can be simulated by having the "main program” just 
contain the macro definitions and call, in turn, all the 
others by the PUT opcode. 
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This is just a convenient way to equate the variables ] 1 
- ] 8* 11 VAR 3; $42 ; LABEL 15 will set ] 1 = 3 , ] 2 - $42, and 

] 3 - LABEL, This is designed for use just prior to a 
PUT, If a PUT file uses ] 1 - ] 8, except in >>> lines 
for calling macros, there MUST be a previous declaration 
of these. 


.7*6 . SAV 


AV filename. 


SAVE FILENAME, (drive and slot parameters accepted) will 
save the current object code under the specified name. 
This acts exactly as does the EXEC mode object saving 
command, but it can be done several times during 
assembly , 


This pseudo-opcode provides a means of saving portions 
of a program having more than one ORG. It also enables 
the assembly of extremely large files. After a save, 
the object address x s reset to the xas t specification of 
OBJ or to HXMEM by default* 
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The SAVE command sets the address of the saved file to 
its correct value. For example , if your program con- 
tains three SAV commands, then it will be saved in three 
pieces. When BLOADed later, they will go to the correct 
locations, the third following the second and that fol- 
lowing the first. 

Together, the PUT and SAV opcodes make it possible to 
assemble extremely large files. 


6*7,7* DSK 
DSK filename 

DSK FILENAME will direct the assembler to assemble the 
following code directly to disk. If DSK is in effect, 
the old file will be closed and the new one begun. This 
is useful primarily for extremely large files* For 
moderately sized programs, SAV is preferred since it is 
30% faster and theoretically more reliable* Because of 
the way it works, the CHK opcode is incompatible with 
DSK and will be disabled if DSK is in effect. 


6,7,8, END 

This rarely used or needed pseudo opcode instructs the 
assembler to ignore the rest of the source. Labels 
occurring after END will not be recognized* 
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6.8* Formatting 


6,8.1. LSI ON/ OFF 
LST ON or OFF (LiST) 

This controls whether the assembly listing is to be sent 
to the Apple screen and/or other output device. You 
may, for example, use this to send only a portion of the 
assembly listing to your printer. Any number of LST 
instructions may be in the source. If the LST condition 
is OFF at the end of assembly, then the symbol table 
will not be printed. The assembler actually only checks 
the third character of the operand to see whether or not 
it is a space. 

Therefore, LST ERINE will have the same effect as LST 
OFF. The LST directive will have no effect on the 
actual generation of object code. If the LST condition 
is OFF, the object code will be generated much faster, 
but this is recommended only for debugged programs, 

NOTE: CONTRGL-D from the keyboard toggles this flag 
during the second pass. 


6.8,2. EXP ON/OFF 
EXP ON or OFF (EXPand) 

EXP ON will print an entire macro during the assembly. 
The OFF condition will print only the PMC pseudo-op. 
EXP defaults to ON, This has no effect on the object 
coded generated. 
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6 * 8 * 3 « PAU 
PA.U (PAUse) 

On the second pass this causes assembly to pause until 
a key is hit* This can also he done from the keyboard 
by hitting the space bar* 


6*8*4# PAG 
PAG (PAGe) 

This sends a formfeed ( $ 8 G ) to the printer* It has no 
effect on the screen listing even when using an 80- 
column card® 


6*8*5. AST 

AST expression (ASTerisks ) 

This sends Asterisks to the listing, the same number as 
the value of the operand# The number format is the 
usual one, so that AST 10 will send (decimal) 10 
asterisks, for example# The number is treated modulo 
256 with 0 being 256 asterisks! This differs from TED 
11+, which recognizes the operand as a hex expression, 
and will need to be converted. 


6*8.6. SKP 

SKP expression (SKIP) 

This sends OPERAND number of carriage returns to the 
listing. The number format is the same as in AST. 
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8 * 8 • 7 * TR 
TR opcode 

This has the same effect in the assembler as does the 
EDITOR TR command, TR or TR ON limits object code 
printout to three bytes per line, and TR OFF resets it 
to print all object bytes. 


ft 3,. ^5 


6*9*1. ASC 

ASC dstring (ASCii) 

This puts a delimited ASCII string into the object 
code. The only restriction on the delimiter is that it 
does not occur in the string itself. Different de- 
limiters have different effects. Any delimiter less 
than (in ASCII code) the single quote (') will produce a 
string with the high-bits on, otherwise the high-bits 
will be off. For example, the delimiters ! 5I #$%& will 
produce a string in "negative" ASCII, and the delimiters 
'()+? will produce one in "positive 51 ASCII, Usually the 
quote (") and single quote (') are the delimiters of 
choice, but other delimiters provide the means of in- 
serting a string containing the quote or single quote 
as part of the string. 


6 ,9, 2* DC I 

DCI d-string (Dextral Character Inverted) 

This is the same as ASC except that the string is put 
into memory with the last character having the opposite 
high bit to the others* 
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6.9.3* INV 

INV d-string (INVerse) 

This puts a delimited string in memory in inverse for- 
mat* All choices of delimiter have the same effect* 


6*9*4, FLS 

FLS d-string (FLaSh) 

This puts a delimited string in memory in flashing for- 
mat* All choices of delimiter have the same effect* 


6,9,5* REV 

REV d-string (REVerse) 

Example : REV 5? DI$K VOLUME” gives; 

EMULOV K3ID (delimiter choice as in ASC) 


6*10* Data and Allocation 


6*10*1, DA 

DA expression (Define Address) 

This stores the (two-byte) value of the operand, usually 
an address , in the object code, low-byte first, DA 
$FDF0 will generate F0 FD, Also accepts multiple data 
(e,g* DA 1,10,100) 
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6.10.2. DBB 

DDB expression (Define Double-Byte) 

As above, but places high-byte first. Also accepts 
multiple data (e .g. DDB 1,10, 100), 


6,10*3, DFB 

DBF expression (DeFine Bytes) 

This puts the bytes specified by the operand into the 
object code. It accepts several bytes of data, which 
must be separated by commas and contain no spaces* The 
standard number format is used and arithmetic is done as 
usual , The symbol is acceptable but ignored, as is 
H < M , The n >” symbol may he used to specify the high- 
byte of the label , otherwise the low-byte is always 
taken. The u > !? symbol should appear only as the first 
character of an expression or immediately after #, That 
is , the instruction DFB /'LABI —LAB 2 will produce the 
high-byte of the value of LAB 1 -LAB 2, 

For example; 

DFB $34 , 100 , LAB 1 -LAB 2 , % 1 0 1 1 , >LAB 1 -LAB 2 

is a properly formatted DFB statement which will gen- 
erate the object code (hex) 34 64 BE 0B09, assuming that 
LAB1=$81A2 and LAB2=$77C4, 


59 



MERLIN Users Manual 


THE ASSEMBLER 


6.10,4. HEX 
HEX hex data 

This is an alternative to DFB which allows convenient 
insertion of hex data. Unlike all other cases, the "$" 
is not required or accepted here. The operand should 
consist of hex numbers having two hex digits (e.g. 0F, 
not F). They may be separated by commas or may be 
adjacent. An error message will be generated if the 
operand contains an odd number of digits or ends in a 
comma, or, as in all cases, contains more than 64 
characters . 


6.10.5. DS 

DS expression (Define Storage) 

This reserves space for string storage data. It does 
not generate code. DS 10, for example, will set aside 
10 bytes for storage. Because DS adjusts the object 
code pointer, and instruction like DS-1 can be used to 
back up the object and address pointers one byte. 


6.10.6. KBD 
KBD (KeyBoarD) 

This allows a label to be equated from the keyboard 
during assembly. Its syntax is: LABEL KBD. 
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6.10.7. LUP 

LUP expression (Loop) 

— ~ (end of LUP) 

An example of the syntax for this is: 

LUP 4 
ASL 

This will assemble as: 

ASL 

A*SL 

ASL 

ASL 

and will show that way in the assembly listing, with 
repeated line numbers* 

Perhaps the major use of this is for table building* As 
an example: 

] A - 0 

LUP $FF 
]A * ] A+l 

DFB ] A 

A 

will assemble the table 1, 2, 3, .. f $FF. The maximum 
LUP value is $8000 and the LUP opcode will simply be 
ignored if you try to use more than this. 
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6*10,8. CHK 

CHK expression (CHecKsum) 

This places a checksum byte into object code at the 
location of the CHK opcode (usually at the end of the 
program)* It cannot be used when DSK is in effect* 


6*10*9* ERR 

ERR expression (ERRor ) 

ERR expression will cause a forced error if the expres- 
sion has a non-zero value and the message ’’Break in line 
? ? ?" is printed* 

This may be used to ensure your program does not exceed, 
for example, $95FF by adding the final line: 

ERR *-l/$9600 

NOTE: This would only alert you that the program is too 

long, and will not prevent writing above $9600 during 
assembly, but there can be no harm in this . The error 
occurs only on the second pass of the assembly and does 
not abort the assembly* 

Another available syntax is: 

ERR ($300)-$4C 

which will produce an error on the first pass, and abort 
assembly, if location $300 does not contain the value 
$4C* 
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6,10,10. USR 
USR (opcode) 

This is a user definable pseudo opcode* It does a. JSR 
$B6DA» This location will contain an RTS after a boot, 
a BRUM MERLIN or BRUN BOOT ASM* To set up your routine 
you should BRUN it from the EXEC command after CATALOG. 
This should just set up a JMP at $B6DA to the main 
routine and then RTS* The following flags and entry 
points may be used by your routine: 


US 'RADS 

- $B6DA 

;must have a JMP to your routine 

PUTBYTE 

= $E5F6 

; see below 

EVAL 

= $E5F9 

; see below 

PASSNUM 

- $2 

; contains assembly pass number 

ERRCNT 

- $1D 

; error count 

VALUE 

- $55 

; value returned by EVAL 

OPNDLEN 

- $BB 

; contains combined length of 
; operand and comment 

N0TF0UN 

- $FD 

; see discussion of EVAL 

WORKS? 

- $280 

; contains the operand and 


; comment in positive ASCII 


Your routine will be called by the USR opcode with A=0, 
Y=0 and carry set* To direct the assembler to put a 
byte in the object code, you should JSR PUTBYTE with the 
byte in A, 

PUTBYTE will preserve Y but will scramble A and X* It 
returns with the zero flag clear (so that BNE always 
branches)* On the first pass, PUTBYTE adjusts the 
object and address pointers, so that the contents of the 
registers are not important* You MUST call PUTBYTE the 
SAME NUMBER OF TIMES on each pass or the pointers will 
not be kept correctly and the assembly of other parts of 
the program will be incorrect! 
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If your routine needs to evaluate the operand, or part 
of it, you can do this by a JSR EVAL. The X register 
must point to the first character of the portion of the 
operand you wish to evaluate (put X=0 to evaluate the 
expression at the start of the operand). On return from 
EVAL, X will point to the character following the ev- 
aluated expression. The Y register will be 0, I, or 2 
accordingly as this character is a right parenthesis, a 
space or a comma. 

Any other character not allowed in an expression will 
cause assembly to abort with a BAD OPERAND error. If 
some label in the expression is not recognized then 
location NOTFOUND will be non-zero. On the second pass, 
however , you will get an UNKNOWN LABEL error and the 
rest of your routine will be ignored. On return f rom 
EVAL , the computed value of the expression will be in 
location VALUE , VALUER- 1 , lowbyte first. On the first 
pass this value will be insignificant if NOTFOUND is 
non-zero • 

Appropriate locations for your routine are $300-$3CF and 
$8A0~$8FF. You must not write to $900* For a longer 
routine, you may use high memory, just below $9853, If 
you are sure that the symbol table will not exceed $1000 
bytes , you could use the SYM EDITOR command to protect 
your routine from overwrite by the object code, SYM 
would have to be set at least one byte below your code. 
You may use zero page locations $60-$6F, but should not 
alter other locations , Also, you must not change any- 
thing from $226 to $27F, or anything from $2C4 to $2FF, 
Upon return from your routine (RTS), the USR line will 
be printed (on the second pass). 
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To gain further understanding of the use of USR, read 
the source file SCRAMBLERS or, for a more sophisticated 
example, the file FLOAT. S. The first of these uses the 
USR opcode to put an ASCII string into the object code 
in a scrambled format. The second is a somewhat comp- 
licated routine that uses Applesoft to compute the 
packed (five-byte) form of a specified floating point 
number, and put it in the object code. Here, the latter 
can be used for assembly only on an Apple ] [ Plus. 

When you use the USR opcode in a source file, it is wise 
to include some sort of check (in source) that the 
required routine is in memory. If, for example, your 
routine contains the byte $31 at location $310 then: 

ERR ($310)-$ 3 

will test that byte and abort assembly if it is not 
there. Similarly, if you know that the required routine 
should assemble exactly two bytes of data, then you can 
(roughly) check for it by the following code: 

LABEL USR OPERAND 

ERR * -LABEL- 2 

This will force an error on the second pass if USR does 
not produce exactly two object bytes* 

It is possible to use USR for several different routines 
in the same source* For example, your routine could 
check the first operand expression for an index to the 
desired routine and act accordingly. Thus "USR 1, 
whatever" would branch to the first routine, "USR 
2, stuff" to the second, etc. 
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6*11® Conditionals 


6 • 1 1 • 1 * DO 
DO expression 

This , together with ELSE and FIN are the conditional 
assembly PSEUDO-OPS® If the operand evaluates to ZERO, 
then the assembler will stop generating object code 
(until it sees another conditional)® Except for macro 
names, it will not recognize any labels in such an area 
of code. If the operand evaluates to a non-zero number, 
then assembly will proceed as usual. This is very 
useful for MACROS. It is also useful for sources de- 
signed to generate slightly different code for different 
situations® For example , if you are designing a program 
to go to on a ROM chip , you would want one version for 
the ROM, and another, with small differences to create a 
RAM version for debugging purposes® 

Similarly, in a program with text, you may wish to have 
one version for Apples with lower case adapters and one 
for those without® By using conditional assembly, 
modification of such programs becomes much simpler, 
since you do not have to make the modification in two 
separate versions of the source code. Every DO should 
be terminated somewhere later by a F IN and each FIN 
should be preceded by a DO® An ELSE should occur only 
inside such a DO, FIN structure. DO, FIN structures may 
be nested up to eight deep (possibly with some ELSE's 
between). If DO condition is off (value 0), then 
assembly will not resume until its corresponding FIN is 
encountered, or an ELSE at this level occurs. Nested 
DO, FIN structures are valuable for putting conditionals 
in MACROS. 
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6,11*2* ELSE 

This inverts the assembly condition (ON — >OFF OR OFF — > 
ON) for the last DO, 


6,11,3, FIN 

This cancels the last DO, 


6,12, Macros 


6,12,1* MAC 
MAC (MACro) 

This signals the start of a MACRO definition. It must 
be labeled with the macro name. The name you use is 
then reserved and cannot be referenced by things other 
than the PMC PSEUDOOP (things like DA NAME will not be 
accepted if NAME is the label on MAC) • However, the 
same thing can be simulated by preceding the MACRO with 
LABEL EQU or LABEL DS 0 , etc. There is rarely any 
need to do this. See the section on MACROS for details 
of the usage of macros, 

EOM ( «< ) 

EOM (End Of Macro) 

<« (alternative syntax) 

This signals the end of the definition of a macro. It 
may be labeled and used for branches to the end of a 
macro, or one of its copies. 
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6*12,2* PMC ( »> ) 

PMC macro name (Put MaCro) 

»> macro name (alternative syntax) 

This instructs the assembler to assemble a copy of 
the named macro at the present location* See the 
section on MACROS. It may be labeled* 


6,13* Variables 

Labels beginning with M ] H are regarded as VARIABLES, These 
may be defined only by EQU and cannot be used to label some- 
thing else. They can be redefined as often as you wish. The 
designed purpose of variables is for use in MACROS, but they 
are not confined to that use. 

Forward reference to a variable is impossible (with correct 
results) but the assembler will assign some value to it* 
That is, a variable should be defined before it is used. 
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7 * MACROS 


7*1# Defining a Macro 
A macro definition begins with 
NAME MAC (no operand) 

and NAME in the label field. Its definition is terminated by 
the pseudo-op EOM or <<<, The label NAME cannot be refer- 
enced by anything other than PMC NAME (or »> NAME), 

You can define the macro the first time you wish to use it in 
the program. However, it is preferable (and required if the 
macro uses variables) to first define all macros at the start 
of the program with the assembly condition OFF and then refer 
to them when needed. 

Forward reference to a macro definition is not possible, and 
would result in a NOT MACRO error message. That is, the 
macro must be defined before it is called by PMC, 

The conditionals DO, ELSE and FIN may be used inside a macro. 

Labels inside macros, such as LOOP and OUT in the example on 
page 5-5, are updated each time PMC is encountered. 

Error messages generated by errors in. macros usually abort 
assembly, because of possibly harmful effects. Such messages 
will usually indicate the line number of a PMC rather than 
the line inside the macro where the error occurs. 


7,2, Nested Macros 

Macros may be nested to a depth of 15, For nesting , macros 
must be defined with DO condition off. 
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Here is an example of a nested macro in which the definition 
itself is nested* (This can only be done when both defini- 
tions end at the same place*) 

TRDB MAC 

yyy tr* 3 1+1 * 9 ] 2+1 

IR MAC 

LDA ] 1 
SIA ] 2 
<« 

In this example »> TR*LOC; DEST will assemble as: 

LDA LOC 
SIA DEST 

and »> IRDR. LOC; DEST will assemble as: 

LDA LOC+1 
STA DESl+l 

LDA LOC * 

STA DEST 

A more common form of nesting is illustrated by these two 
macro definitions (where CH ~ $24): 

POKE MAC 

LDA #] 2 
STA ]1 
«< 

HTAB MAC 

yyy poke * ch ; 3 1 
«< 
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7.3. Special Variables 

Eight variables, named ]1 through ]8, are predefined and are 
designed for convenience in MACROS. These are used in a PMC 
statement. The instruction: 

»> NAME expr 1 ; expr2;expr3. . , 

will assign the value of exprl to the variable ] 1 , that of 
expr2 to ]2, and so on. An example of this usage is: 

TEMP EQU $10 

DO 0 

SWAP MAC 

LDA ] 1 

STA ] 3 

LDA ] 2 

STA ] 1 

LDA ] 3 

STA ] 2 

«< 

FIN 

»> SWAP $6 ; $7 ; TEMP 

»> SWAP $1000; $6 ; TEMP 

This program segment swaps the contents of location $6 with 
that of $7, using TEMP as a scratch depository, then swaps 
the contents of $6 with that of $1000. 

If, as above, some of the special variables are used in the 
MACRO definition, then values for them must be specified in 
the PMC (or >>>) statement. In the assembly listing, the 
special variables will be replaced by their corresponding 
expressions , 

The number of values must match the number of variables in 
the macro definition. A BAD OPERAND error will be generated 
if the number of values is less than the number of variables. 
No error message will be generated, however, if there are 
more values than variables. 
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The assembler will accept some other characters in place of 
the space between the macro name and the expressions in a PMC 
statement* For example, you may use any of these characters: 

• / * ” c 

The semicolons are required, however, and no extra spaces are 
allowed * 

Macros will accept literal data. Thus the assembler will 
accept the following type of macro call: 

DO 0 
MUV MAC 

LDA ]1 
STA ] 2 

«< 

FIN 

»> MUV. (PNTR),Y; BEST 
»> MUV, #3 ; FLAG, X 

It will also accept: 

DO 0 
PRINT MAC 

JSR SENDMSG 
ASC ] 1 
BRK 
«< 

FIN 

»> PRINT. ! "quote”! 

>» PRINT. 'This is an example*' 

>>> PRINT. "So's this, understand? 51 

LIMITATION: If such strings contain spaces or semicolons, 
they MUST be delimited by quotes (single or double)* Also, 
literals such as >>> WHAT ."A" must have the final delimiter* 
(This is only true in macro calls or VAR statements, but it 
is good practice in all cases.) 
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A previous version of this assembler, that did not have this 
capability, used commas rather than semicolons in >>> 
statements* For people who have that version, a program 
"CONVERT" has been provided which changes these commas to 
semicolons in a matter of a second or two* With the source 
file in memory, it should be BRUN from the EXEC mode's 
Command after Catalog* 


7 » A’ ® Sample "Program 

Here is a sample program intended to illustrate the usage of 
macros with non-standard variable. It would, however, be 
simpler and more pleasing if it used ] 1 instead of ] MSG (in 
which case the variable equates should be eliminated and the 
values for ] 1 must be specified in the »> lines,) 


HOME 

EQU 

$FC58 

COUT 

EQU 

$FDED 

KEY 

EQU 

$C00Q 

STROBE 

EQU 

$CQ1Q 

DOS 

EQU 

$3D3 


DO 

0 

SENDMSG 

MAC 



LDY 

#0 

LOOP 

LDA 

]MSG,Y 


BEQ 

OUT 


JSR 

COUT 


I NY 



BNE 

LOOP 

OUT 

<« 



FIN 



JSR 

HOME 

]MSG 

EQU 

HITMSG 


»> 

SENDMSG 

INVRS 

CMP 

#"I" 


BNE 

NORM 

] MSG 

EQU 

IMSG 


»> 

SENDMSG 


;Assembly off 

; Start of definition of the 
;macro "SENDMSG" 

;Get a character 
;End of message 
; Send it 

;Back for more 

; End of macro definition and 
;exit from routine 
;Turn assembly ON 
; Clear screen 
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NORM 

CMP 

#"N" 



BNE 

STP 


]MSG 

EQU 

NMSG 



»> 

SENDMSG 


STP 

CMP 

#"S" 

;Does he want to stop? 


BNE 

GETKEY 

;No , get the next input 


JMP 

DOS 

; All done, exit gracefully 

HITMSG 

ASC 

!HIT 

;A KEY "F” , "I st , ,! N n , OR "S"! 


HEX 

8D8D00 


FMSG 

FLS 

"THIS IS 

A FLASHING MESSAGE” 


HEX 

8D8D00 


IMSG 

INV 

"THIS IS 

A MESSAGE IN INVERSE” 


HEX 

D8D00 


NMSG 

ASC 

"THIS IS 

A NORMAL MESSAGE” 


HEX 

8D8D00 



7,5, The Macro Library 

A macro library with three example macro programs is included 
in source file form on this diskette. The purpose of the 
library is to provide some guidance to the newcomer to macros 
and how they can be used within an assembly program. 

NOTE: All macros are defined at the beginning of the source 
file, then each example program places the macros where they 
are needed. Conditionals are used to determine which example 
program is to be assembled. The KBD opcode allows the user 
to make this selection from the keyboard during assembly. 
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8. TECHNICAL INFORMATION 


The SOURCE is placed at $901 when loaded, regardless ot its 
original address. 

The important pointers are : 

START OF SOURCE in $A,$B (always set $901) 

HIMEM in $C,$D (defaults to $8000) 

END OF SOURCE in $E,$F 

When you exit to BASIC or to the monitor, these pointers are 
saved at $E0 0 A-$E00 F. They are restored upon re-entry to 
MERLIN. 

Entry into MERLIN replaces the current I/O hooks with the 
standard ones and reconnects DOS. This is the same as typing 
PR#0 and IN#0 from the keyboard. Entry to the EDITOR discon- 
nects DOS , so that you can use labels such as INIT w i thou t 
disastrous consequences . Re-entry to EXEC MODE disconnects 
any 1/ 0 hooks that you may have established via the editor's 
PR# command, and reconnects DOS. Exit from assembly (com- 
pletion of assembly or CTRL-C) also disconnects I/O hooks. 


8.1. General Information 

Re-entry after exit to BASIC is made by the "ASSEM" command. 
A BRUN MERLIN or a disk boot will also provide a warm re- 
entry and will not reload MERLIN if it is already there. 
This may be forced by BRUN BOOT ASM which would then be a 
cold entry, "destroying" any file in memory. 

Memory organization, for ordinary sized files is of no con- 
cern to the user, but it is important to understand certain 
constraints for the handling of large files. HIMEM (which 
defaults to $8000) is an upper limit to the source file. It 
is also an upper limit for PUT files. If a memory error 
occurs during assembly, indicating a PUT line, it means the 
PUT file exceeded HIMEM and that HIMEM will have to be 
increased . 
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The default ORG and OBJ addresses equal the present value of 
HIMEM, It is illegal to specify an OBJ address that is less 
than HIMEM except that a page 3 address is allowed* If a 
page 3 OBJ address is used, the user MUST be careful that the 
file will not write over the DOS jumps at $3D0~$3FF as the 
assembler does NOT check for this error. If , during assem- 
bly, the object code exceeds BASIC HIMEM (or the SYM address, 
if one has been, specified) then the code will not be written 
to memory, but assembly will appear to proceed and its output 
sent to the screen or printer* The only clue that this has 
happened, if not intentional, is that the object SAVE command 
is disabled in this event. Therefore, if a listing for a 
very long file is desired, without actually creating code, 
the user can assemble over DOS and up. 
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8*2* MERLIN Memory Map (Ram Card Version) 


SFFFF 


$D00Q 

$DOOO 


MERLIN 


(D Bonk 2) 


NORMAL SYMBOL TABLE 
p] (D Bank 1) 


66535 


53248 

53248 


APPLESOFT HIMEM: ($73.74) 



$9852 

SYM 


MERUN HIMEM: ($C.D)— **$8000 
END OF SOURCE ($E.F) 1 ► 

BEG, OF SOURCE ($A.B)-^ $901 

$8FF 

$8A0 

$800 


□. 

(Excess Symbol Table * 
From Ram Card) i 


FREE SPACE 


n 

1 

i 

□ 




i 

SOURCE RLE 

i 


FREE SPACE 

MS SC. USE 
BY MERUN 


53247 

49152 

49151 

38995 

38994 


32768 

ALSO CAN BE FOUND WITH "WO" 
COMMAND FROM EDIT MODE 

2305 

2303 

2228 

2048 


$7FF 

$400 

$300 

$300 

$200 

$100 

$0 


i 

SCREEN MEMORY 

— .J 

i 

PAGE 3 

dos/mon vectors 

PAGE 3 
USER SPACE 


PAGE 2 
(Input Buffer) 

i 

PAGE 1 
(Stack) 


PAGE 0 

(Ml$c. Pointers) 


2047 

1024 

976 

768 

510 

256 

($60.6F UNUSED) 

0 
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8.3* MERLIN Memory Map (48k Version) 


$BFFF 


S9D00 


S73F8 


APPLESOFT HIMEM: ($73.74) — *~$6F53 □ 


$6000 Li 


MERUN HIMEM: ($C.D) — ► $5000 Q 


END OF SOURCE ($E.F)< 


BEG, OF SOURCE ($A.B)— *~$901 Q 


•$8FF 

$8A0 


$800 Q 




$7FF 

$400 

$3D0 

$300 

$200 

$100 

$0 


H 

H 


DOS 


MERUN 


DOS BUFFERS 

( 2 ) 


SYMBOL TABLE 


i k 


OBJECT CODE 


SOURCE FILE 


FREE SPACE 


MISC. USE 
BY MERUN 


SCREEN MEMORY 


PAGE 3 

DOS/ MON VECTORS 


IL 

IL 


PAGE 3 
USER SPACE 


PAGE 2 
(Input Buffer) 


n 


PAGE 1 
(Stack) 


PAGE 0 

(Misc, Pointers) 


49151 


40192 


29688 

28499 

24576 

20480 


ALSO CAN BE FOUND WITH "W0' 
COMMAND FROM EDIT MODE 


2305 

2303 

2228 

2048 

2047 

1024 

976 

768 

510 

256 

($60.6F UNUSED) 

0 
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8.4. Symbol Table 

The symbol table is printed after assembly unless LST OFF has 
been invoked. It comes first in alphabetical order and then 
in numerical order. The symbol table is flagged as follows: 

MD = Macro Definition 

M = Label defined in a macro (LOOP and OUT in the 

example) 

V = Variable (symbols starting with ]) 

? = A symbol that was never referenced 

Internally, these are flagged by setting bits 7 to 4 of the 
symbols length byte: 

2-hit 7 MD-bit 5 M-bit 4 

Also, bit 6 is set during the alphabetical printout to flag 
printed symbols, then removed during the numerical order 
printout. The symbol printout is formatted for an 80 column 
printer, or for one which will send a carriage return after 
40 columns. 


8.5. Using MERLIN With Shift Key Mods 

MERLIN supports all hardware shift key modifications. The 
CONFIGURATION program will establish the modification that 
you want supported. MERLIN is smart enough to know if the 
modification actually exists in the Apple you are using and 
defeats the modification if it is not there. Thus it can be 
used on another machine without reconfiguration. 
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8.6 * Using MERLIN With 80 Column. Boards 

Most , but not all , 80 column boards are supported. You may 
use the VIDEO command to enable the 80 column board* To have 
the board selected upon boot, use the CONFIGURATION program. 
Then the VIDEO 0 or $10 command followed by RESET will switch 
back to the normal Apple screen. 

If your board does not support inverse, control characters in 
the source will show as ordinary capital letters instead of 
inverse letters as with boards that support inverse. You can 
use the editor's FIND command to search for particular con- 
trol characters, verify their presence or absence, or simply 
switch over to the normal Apple screen. 

If your copy of MERLIN has been configured to support an 80 
column card in slot 3, and there is no card in that slot, 
MERLIN will recognize this and defeat the 80 column pro- 
vision. There is no need to reconfigure for use on another 
computer • 

MERLIN will NOT support any board that does not recognize the 
’’POKE 36” method of tabbing. As far as we know this only 
means it will not support older versions of the FULL VIEW 80 
card . 

When in EDIT mode, MERLIN takes total control of input and 
output* The effect of typing a control character will be as 
described in this manual and NOT as described in the manual 
for your 80 column card. For example, CTRL-L will not blank 
the screen, but is the case toggle. CTRL-A, which acts as a 
case toggle on many 80 column cards, will not do this in EDIT 
mode and simply produces a CTRL-A in the file line. 
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8,7* The Configure ASM Program 

This program allows you to make several minor modifications 
to MERLIN's default conditions. It allows you to change the 
,! UPDATE SOURCE" character searched for at the entry to the 
assembler, the editor's wild card character, and the number 
of symbol fields printed per line in the symbol table print”" 
out. It also allows you to specify whether you want to have 
an 80 column, board supported, and if so, which slot it is in. 

You can also specify a hardware shift key modification. Any 
such modification can be supported. However, if your modifi- 
cation is the type that enables direct input of lower case 
(as with the VIDEX Keyboard Enhancer) instead of providing a 
memory location to be tested (as with the "game button 2" 
modification), then the default at the start of each line 
will be lower case rather than upper case and CTRL-L will 
function as a case lock toggle. 

It allows you to specify whether you have a lower case 
adaptor. This will affect the condition on boot if you have 
not elected to have an. 80 column board selected. It may 
always be defeated from the editor using the VIDEO command, 
so this only selects the initial condition. 

You may select a number of other options including certain 
printer options for use by the PRTR command. 

Finally, you can save the configured version to another, or 
the same disk. There is no reason to keep the original 
version since you can always return to it by reconfiguration. 

At the end of the configuration program the user is given the 
opportunity to transfer the boot program "MERLIN" to another 
disk. This is jus t a convenient way of transferring that 
program since it cannot be done manually. You can also use 
FID to copy MERLIN or ASM. OBJ (the main program.) 
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NOTE: MERLIN will RUN only on the original disk or a pro- 
tected copy. The files may be kept for safety on another 
disk, but cannot function until recopied onto a protected 
disk. The configuration program should be BRUN only when the 
standard Apple screen is in use. 


8,8. Error Messages 


8,8.1, BAD OPCODE 

Occurs when the opcode is not valid (perhaps misspelled) 
or the opcode is in the label column® 


8.8.2. BAD ADDRESS MODE 

The addressing mode is not a valid 6502 instruction; for 
example, JSR (LABEL) or LDX (LABEL), Y. 

8.8.3. BAD BRANCH 

A branch (BEQ, BCC, etc) to an address that is out of 
range, i.e. further away than +127 bytes. 

NOTE : Most errors will throw of f the assembler's 

address calculations. Bad branch errors should be 
ignored until previous errors have been dealt with. 


8.8.4. BAD OPERAND 

An illegally formatted operand. This also occurs if you 
"EQU ,f a label to a zero page number after the label has 
been used. It may also mean that your operand is longer 
than 64 characters , or that a comment line exceeds 64 
characters. This error will abort assembly. 
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8,8.5, DUPLICATE SYMBOL 

On the first pass, the assembler finds two identical 
labels . 


8.8.6. MEMORY FULL 

This is usually caused by one of four conditions; 
Incorrect OBJ setting, source code too large, object 
code too large or symbol table too large. See "Special 
Note" at the end of this section. 


8.8,7. UNKNOWN LABEL 

Your program refers to a LABEL that does not exist. 
This also occurs if you try to reference a MACRO defini- 
tion by anything other than PMC, It can also occur if 
the referenced label is in an area with conditional 
assembly OFF, The latter will not happen with a MACRO 
definition. 


8.8,8, NOT MACRO 

Forward reference to a MACRO, or reference by PMC to a 
label that is not a MACRO. 


8.8.9. NESTING ERROR 

Macros nested more than 15 deep or conditionals nested 
more than 8 deep. 


8.8.10. BAD "PUT" 

This is caused by a PUT inside a macro or by a PUT 
inside another PUT file. 
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8 .8.11. BAD "SAV" 


This is caused by a SAV inside a macro or a SAV after a 
multiple OBJ after the last SAV. 


8*8.12* BAD INPUT 

This results from either no input ( [RTN ] alone) or an 
input exceeding 37 characters in answer to the KBD op- 
code's request for the value of a label. 


8*8.13* BREAK 

This message is caused by the ERR opcode when the ex- 
pression in the operand is found to be nonzero. 


8.8*14, BAD LABEL 

This is caused by an unlabeled EQU or MAC* a label that 
is too long or one containing illegal characters. 


8,9. Special Note - Memory Full Errors 

There are four comm. on causes for the "memory full" error 
message, A more detailed description of this problem and 
some ways to overcome it follow* 

ERROR ME, S SAGE: "MEMORY FULL IN LINE: n". Generated during 
pass 1 prior to assembly (line number points to an OBJ in- 
struction), CAUSE: An OBJ was specified that was below 
MERLIN'S HIMEM (normally $8000) and also not within Page 3 
($300. 3FF), MERLIN will not allow you to put object code in 
this range in order to protect your source file and the 
system* REMEDY: Remove the OBJ instruction or change it to 
specify an address within the legal range. 


OR. MESSAGE 
er you typ 
too large 
the RAM Gc 
se MERLIN'i 
break the 
m in when 


Generated immediately 
ty. CAUSE: The source code 
IN's HIMEM (normally $8000 
the 48K version). REMEDY: 
ion on the HIMEM command) 
mailer sections and bring 
2 ■ "PUT 11 pseudo-op. 


OR MESSAGE 
embly. CA 
ibol table 
_ 1 v $9853 : 


: n ,! . Generated during 
y symbols have been placed into the 
. to exceed Applesoft's HIMEM (nor- 
card version and $6F53 for the ASK 
he symbol table larger by using the 
beginning address. 

no object code will be generated 
information displayed on the EXEC 
e generated from an assembly would 
table or Applesoft's HIMEM. REMEDY: 
write the object code directly to 
LO-Op. 


using 


M 
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9. SOURCEROR 


9 ® 1 » 


SOURCEROR is a sophisticated and easy to use disassembler 
designed as a subsidiary to create MERLIN source files out of 
binary programs, usually in a matter of minutes, SOURCEROR 
disassembles SWEET 16 code as well as 6502 code. 

The main part of SOURCEROR is called SRCRR.OBJ, but this 
cannot be run (conveniently) directly, since it may overwrite 
DOS buffers and crash the system. For this reason , a small 
program named SOURCEROR is provided. It runs in the input 
buffer, and does not conflict with any program in memory. 
This small program simply checks memory size, gets rid of any 
program such as RLE which would conflict with the main 
SOURCEROR program, sets MAXFILES 1 , then runs SRCRR,OBJ (at 
$8800-~$9AA5) * 

To minimize the possibility of accident , SRCRR.OB J has a 
default location of $4000 and if you BRUN it, it will just 
return without doing anything. If you try to BRUN it at its 
designed location of $8800, however, you could be in for big 
trouble* SOURCEROR assumes the standard Apple screen is 
being used and will not function with an 80 column card. 


9.2, Using SOURCEROR 

1. Load in the program to be disassembled. Although 
Sourceror will handle programs at any location, the 
original location for the program is preferable as long 
as it will not conflict with SOURCEROR and the build up 
of the source file. When in doubt , load it in at $800 or 
$80 3. Small programs at $4000 and above, or medium 
sized ones above $6000 will probably be okay at their 
original locations, 

2, BRUN SOURCEROR 
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3, You will be told that the default address for the source 
file is $2500* This was selected because it does not 
conflict with the addresses of most binary programs you 
may wish to disassemble® Just hit RETURN to accept this 
default address. Otherwise , specify (in Hex) the ad- 
dress you want. 

You may also access a ’’secret” provision at this point. 
This is done by typing CTRL-S (for "SWEET") after, or in 
lieu of the source address. Then you will be asked to 
specify a (nonstandard) address for the SWEET 16 inter- 
preter. This is intended to facilitate disassembly of 
programs which use a RAM version of SWEET 16. 

4. Next , you will be asked to hit RETURN if the program to 
be disassembled is at its original (running) location, 
or you must specify in Hex, the present location of the 
code to be disassembled. Finally, you will be asked to 
give the ORIGINAL location of that program. 


When disassembling, you must use the ORIGINAL address of 
the program, not the address where the program currently 
resides. It will appear that you are disassembling the 
program at its original location, but actually, 
SOURCEROR is disassembling the code at its present loca- 
tion and translating the addresses. 

5* Lastly, the title page which contains a synopsis of the 
commands to be used in disassembly will display. You 
may now start disassembling or using any of the other 
commands. Your first command must include a Hex ad- 
dress. Thereafter this is optional, as we shall 
explain. 

At this point , and until the final processing , you may 
hit RESET to return to the start of the SOURCEROR pro- 
gram. If you hit RESET once more , you will exit 
SOURCEROR and return to BASIC. Using RESET assumes you 
are using the Autostart monitor rom. 
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9*3® Commands Used in. Disassembly 


The disassembly commands are very similar to those used by 
the disassembler in the Apple monitor® All commands accept a 
4-digit hex address before the command letter* If this 
number is omitted, then the disassembly continues from its 
present address • A number must be specified only upon. 
Initial entry. 

If you specify a number greater than the present address, a 
new ORG will be created. 


More commonly, you will specify an address less than the 
present default value* In this case , the disassembler checks 
to see if this address equals the address of one of the 
previous lines* If so, it simply backs up to that point. If 
not, then it backs up to the next used address and creates a 
new ORG. Subsequent source lines are "erased*! It is gen- 
erally best to avoid new ORGs when possible. If you get a 
new ORG and don't want it, try backing up a bit more until 
you no longer get a new ORG upon disassembly* 


9.4. Command Descriptions 


9.4.1. L (List) 

This is the main disassembly command* It disassembles 20 
lines of code# It may be repeated (e.g* 2000LLL will 
disassemble 60 lines of code starting at $2000). It a 
JSR to the SWEET 16 interpreter is found, disassembly is 
automatically switched to the SWEET 16 mode* 

Command L always continues the present mode of disassem- 
bly (SWEET 16 or normal). 
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If an illegal opcode is encountered, the hell will sound 
and opcode will be printed as three question marks in 
flashing format* This is only to call your attention to 
the situation* In the source code itself, unrecognized 
opcodes are converted to HEX data, but not displayed on 
the screen.* 


9.4.2* S (SWEET) 

This is similar to L, but forces the disassembly to start 
in SWEET 16 mode* SWEET 16 mode returns to normal 6502 
mode whenever the SWEET 16 RTN opcode is found. 


9.4.3. N (Normal) 

This is the same as L, but forces disassembly to start in 
normal 6502 mode. 

9.4.4. H (Hex) 

This creates the HEX data opcode. It defaults to one 
byte of data. If you insert a one byte (one or two 
digits) hex number after the H, that number of data bytes 
will be generated. 


9.4.5. T (Text) 

This attempts to disassemble the data at the current 
address as an ASCII string. Depending on the form of the 
data, this will (automatically) be disassembled under the 
pseudo opcode ASC, DCI, INV or FLS. The appropriate 
delimiter n or ' is automatically chosen. The disassem- 
bly will end when the data encountered is inappropriate, 
when 62 characters have been treated , or when the high 
bit of the data changes. In the last condition, the ASC 
opcode is automatically changed to DCI. 
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Sometimes the change to DCI is inappropriate. This 
change can he defeated by using TT instead of T in the 
command . 

Occasionally, the disassembled string may not stop at the 
appropriate place because the following code looks like 
ASCII data to SOURCEROR. In this event, you may limit 
the number of characters put into the string by inserting 
a one or two digit hex number after the T command. 

This or TT, may also have to be used to establish the 
correct boundary between a regular ASCII string and a 
flashing one. It is usually obvious where this should be 
done . 

Any lower case letters appearing in the text string are 
shown as flashing uppercase letters. 


9.4.6. W (Word) 

This disassembles the next two bytes at the current 
location as a DA opcode. Optionally, if the command WW 
is used, these bytes are disassembled as a DDB opcode. 
Finally, if W— is used as the command, the two bytes are 
disassembled in the form DA LABEL- 1. The latter is often 
the appropriate form when the program uses the address by 
pushing it on the stack. You may detect this while 
disassembling, or after the program has been dis- 
assembled. In the latter case, it may be to your advan- 
tage to do the disassembly again with some notes in hand. 



MERLIN Users Manual 


SOURCEROR 


9*5® Housekeeping Commands 


9*5,1* / ( Cancel ) 

Ibis essentially cancels the last command* More exactly, 
it re-establishes the last default address (the address 
used for a command not necessarily attached to an 
address)® This is a useful convenience which allows you 
to ignore the typing of an address when a backup is 
desired* As an example, suppose you type T to dis- 
assemble some text* You may not know what to expect 
following the text, so you can just type to L to look at 
it® Then if the text turns out to be followed by some 
Hex data (such as $8D for a carriage return), simply type 
/ to cancel the L and type the appropriate H command. 


9*5,2, R (Read) 


This allows you to look at memory in a format that makes 
imbedded text stand out* To look at the data from $1234 
to $1333 type 1234R. After that, R alone will bring up 
the next page of memory* The numbers you use for this 
command are totally independent of the disassembly 
address * 

However, you may disassemble, then use (address)R, then L 
alone, and the disassembly will proceed just as if you 
never used R at all. If you don't intend to use the 
default address when you return to disassembly, it may be 
wise to make a note on where you wanted to resume, or to 
use the / before the R. 
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9.5.3. Q (Quit) 

This ends disassembly and goes to the final processing 
which is automatic. If you type an address before the Q, 
the address pointer is backed to (but not including) that 
point before the processing. If, at the end of the 
disassembly, the disassembled lines includes 

2341- 4C 03 E0 JMP $E003 

2344™ A9 BE 94 LDA $94BE,Y 

and the last line is just garbage, type 2344Q. This will 
cancel the last line, but retain the first. 


9.6. Final Processing 

After the Q command, the program does some last minute pro 
cessing of the assembled code. If you hit RESET at this 
time, you will return to BASIC and lose the disassembled 
code • 

The processing may take from a second or two for a short 
program, to two or three minutes for a long one. Be patient* 

When the processing is done, you are asked if you want to 
save the source. If so, you will be asked for a file name. 
SOURCEROR will append the suffix "*3 ?l to this name and save 
it to disk. 

The drive used will be the one used to BRUM SOURCEROR. Re- 
place the disk first if you want the source to go on another 
disk® 

To look at the disassembled source, BRUM MERLIN , or type 
ASSEM, and load it in. 
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The source will have all the exterior or others 
recognized labels at the end in a table of equat 
should look at this table closely* It should not coi 
zero page equates except ones resulting from DA's , 
JSR's. This is almost a sure sign of an error in th 
semhly (yours, not SOURCEROR's). It may have resul 
an attempt to disassemble a data area as regular cod 

NOTE: If you try to assemble the source under th 
ditions, you will get an error as soon as the equate 
If, as eventually you should , you move the equate 
start of the program, you will not get an error , 
assembly MAY NOT BE CORRECT. It is important to d 
this situation first as trouble could occur if , for 
the disassembler finds the data AD 00 8D, It will c 
ble it correctly, as LDA $008D. 

The assembler always assembles this code as a z 
instruction, giving the two bytes A5 8D. Occasion 
will find a program that uses this form for a z 
instruction. In that case, you wi II have to insert 
acter after the LDA opcode to have it assemble ident: 
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9*8, The Memory Full Message 

When the source file reaches within $600 of the start of 
SOURCEROR (that is, when it goes beyond $8200) you will see 
?, MEMORY FULL” and "HIT A KEY” in flashing format* When you 
hit a key, SOURCEROR will go directly to the final pro- 
cessing* The reason for the $600 gap is that SOURCEROR needs 
a certain amount of space for this processing. It is pos- 
sible (but not likely) that part of SOURCEROR will be over- 
written during final processing, but this should not cause 
problems since the front end of SOURCEROR will not be used 
again by that point. There is a ’’secret” override provision 
at the memory full point. If the key you hit is CTRL-0 (for 
override), then SOURCEROR will return for another command* 
You can use this to specify the desired ending point. You 
can also use it to go a little further than SOURCEROR wants 
you to , and disassemble a few more lines* Obviously, you 
should not carry this to extremes. 

CAUTION : After exiting SOURCEROR, do not try to run it again 
with a CALL. Instead, run it again from disk. This is 
because the DOS buffers have been re-established upon exit, 
and will have partially destroyed SOURCEROR. 


9.9, The LABELER program 

One of the nicest features of the SOURCEROR program is the 
automatic assignment of labels to all recognizable addresses 
in the binary file being disassembled. Addresses are recog- 
nized by being found in a table which SOURCEROR references 
during the disassembly process. For example, all JSR $FC58 
instructions within a binary file will be listed by SOURCEROR 
as JSR HOME, This table of address labels may be edited by 
using the program LABELER, 

To use labeler, BRUN LABELER, The program will then mention 
that SRCRR.OBJ is being loaded into memory , and present the 
main program menu. 
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The demonstration program is written, to be introductory and 
simple, consisting of three parts : 

1* Integer Basic Program 
2* Machine Language Subroutine 
3, SWEET 16 Subroutine 

The task of the program will be to move data* Parameters of 
the move will be entered in the Integer Basic Program* 

The "CALL 768” ($300) at line 120, enters a 6502 machine 
language subroutine having the single purpose of entering 
SWEET 16 and subsequently returning to BASIC (addresses $300, 
$301, $302, and $312 respectively)* The SWEET 16 subroutine 
of course performs the move, and is entered at Hex locations 
$303 to $311 (see listing Number 3)* 

After the move, the screen will display three lines of data, 
each 8 bytes long, and await entry of a new set of para- 
meters. The three lines of data displayed on the screen are 
as follows : 

Line 1* I he first 8 bytes of data starting a $800 , which 
is the fixed source data to be moved (in this 
case , the string A$ ). 

Line 2: The first 8 bytes of data starting at the hex 

address entered as the destination of the 
move (high order byte only). 

Line 3: The first 8 bytes of data starting at $0000 (the 

first four SWEET 16 registers). 

The display of 8 bytes of data was chosen to simplify the 
illustration of what goes on. 

Integer Basic has its own way of recording the string A$, 
Because the name chosen for the string M A$" is stored in 2 
bytes, a total of five housekeeping bytes precede the data 
entered as A$, leaving only three additional bytes available 
for display. Integer Basic also adds a housekeeping byte at 
the end of a string, known as the "string terminator". 
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Consequently, for convenience purposes of the display, and to 
see the string terminator as the 8th byte, the string data 
entered via the keyboard should be limited to two characters, 
and will appear as the 6th and 7th bytes. Additionally, 
parameters to be entered include the number of bytes to be 
moved. A useful range for this demonstration, would be 1-8 
inclusive, but of course 1-255 will work* 

Finally, the starting address of the destination of the move 
must be entered. Again, for simplicity, only the high-order 
byte is entered , and the program allows a choice between 
Decimal 9 and high-order byte of program pointer 1, to avoid 
unnecessary problems (in this demonstration enter a decimal 
number between 9 and 144 for a 48K APPLE). 

The 8 bytes of data displayed starting at $00 will enable one 
to observe the condition of the SWEET 16 registers after a 
move has been accomplished , and thereby understand how the 
SWEET 16 program works. 

From the article "SWEET 16: The 6502 Dream Machine", remember 
that SWEET 16 can establish 16 double byte registers starting 
at $00 . This means that SWEET 16 can use the first 32 
addresses on zero page. 


The "events" occurring in this demonstration program can be 
studied in the first four SWEET 16 registers. Therefore, the 
8 byte display starting at $0000 is large enough for this 
purpose . 


These four registers are established as R0, Rl, R2, R3: 


R0 

$0000 

a 

0001 

Rl 

$0002 

& 

0003 

R2 

$0003 

& 

0004 

R3 

• 

$0004 

& 

0005 

• 

R14 

$001C 

& 

001D 

R15 

$001E 

& 

001F 


-SWEET 16 accumulator 
-Source address 
-Destination address 
-Number of bytes to move 


-Prior result register 
-SWEET 16 Program counter 
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NOTE: A 6502 disassembly does not look like Listing # 

the included SOURCEROR disassembler would create a c 
disassembly * 

Enter l5 RUN l! and hit RETURN 

Enter 1? 12 Sf and hit RETURN (A$ - A$ string data) 
Enter "18" and hit RETURN (high-order by- 
destination) 

The display should appear as follows : 

$0800-01 40 00 10 08 B1 B2 IE (SOURCE) 

$0A00-C1 40 00 10 08 B1 B2 IE (Best*) 

$0000-lE 00 08 08 08 0A 00 00 (SWEET 16) 

NOTE: The 8 bytes stored at $0A00 are identical to 

bytes starting at $0800 , indicating an accurate mov< 
bytes length has been made* They are moved one by t< 
time starting with token Cl and ending with token 13 
moving less that 8 bytes , the data following the mover 
would be whatever existed at those locations before the 
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The bytes have the following significance : 
A Token$ 


Cl 40 00 

10 08 

B1 B2 

IE 

1 1 


7 7 

String 

VN DSP 

NVA 

DATA DATA 

Terminator 

The SWEET 16 registers are shown 

a 


Low high 

low high 

low high 

low high 

$0000 IE 00 

08 08 

08 0A 

00 00 

register 

register 

register 

register 

R0 

Rl 

R2 

R3 

(acc) 

(source ) 

(dest ) 

(kbytes) 


The low order byte of R0, the SWEET 16 accumulator, has $ IE 
in it, the last byte moved ( the 8th). 

The low order byte of the source reg i s ter R1 star ted as $00 
and was incremented eight times , once for each byte of moved 
data » 


The high order byte of the destination register R2 contains 
$0 A, which was entered as 10 (the variable) and poked into 
the SWEET 16 code. The low-order byte of R2 was incremented 
exactly like Rl. 

Finally, register R3, the register that stores the number of 
bytes to be moved, has been poked to 8 (the variable B) and 
decremented eight times as each byte got moved , ending up 
$ 0000 . 

By entering character strings and varying the number of bytes 
to be moved , the SWEET 16 registers can be observed and the 
contents predicted. 
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Working with this demonstration program, and study of the 
text material will enable you to write SWEET 16 programs that 
perform additional 16 bit manipulations. The unassigned 
opcodes mentioned in the "WOZ Dream Machine 11 article should 
present a most interesting opportunity to "play". 

SWEET 16 as a language - or tool - opens a new direction to 
Apple ] [ owners without spending a dime, and it's been there 
all the time* 

"Apple-i tes" who desire to learn machine language program- 
ming, can use SWEET 16 as a starting point. With this text 
material to use, and less opcodes to learn, a user can 
quickly be effective, 

t or those without Integer Basic, SWEET 16 is supplied as a 
source file on this diskette. 


10. 1. Listing #1 


>List 

10 PRINT " [D] BLGAD SWEET 11 : REM CTRL D 

20 CALL - 936: DIM A $ (10) 

30 INPUT "ENTER STRING A $ ", A $ 

40 INPUT "ENTER # BYTES n , B 

50 IF NOT B THEN 40 : REM AT LEAST 1 

60 POKE 778 B ; REM POKE LENGTH 
70 INPUT "ENTER DESTINATION" , A 

80 IF A > PEEK (203) - 1 THEN 70 

90 IF A < PEEK (205) + 1 THEN 70 

100 POKE 776 , A : REM POKE DESTINATION 
110 M » 8 : GOSUB 160 : REM DISPLAY 

120 CALL 768 : REM GOTO $0300 

130 M = A : GOSUB 160 : REM DISPLAY 

140 M = 0 : GOSUB 160 : REM DISPLAY 

150 PRINT : PRINT : GOTO 30 

160 POKE 60 , 0 : POKE 61 , M 

170 CALL -605 : RETURN : REM XAM8 IN MONITOR 
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10.2. Listing #2 

300:20 89 F6 1 

F3 07 FB 00 6i 


10.3. Listing #3 

SWEET 16 

$300 20 89 Fi 

$303 11 00 01 

$306 12 00 0! 

$309 13 00 

] 

$30C 41 

$30D 52 

$30E F3 
$30F 07 

$311 00 

$312 60 

Data will be poked fi 
"A" 1 

Ugll 
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11* SWEET 16 : A Pseudo 16 Bit Microprocessor 


By Steve Wozniak 


11*1* Description. 

While writing APPLE BASIC for a 6502 microprocessor, I re- 
peatedly encountered a. variant of MURPHY'S LAW, Briefly 
stated, any routine operating on 16-bit data will require at 
least twice the code that it should* Programs making exten- 
sive use of 16-bit pointers (such as compilers , editors , and 
assemblers) are included in this category. In my case, even 
the addition of a few double-byte instructions to the 6502 
would have only s lightly alleviated the problem. What I 
really needed was a 6502/RCA 1800 hybrid - an abundance of 
16-bit registers and excellent pointer capability. My solu- 
tion was to implement a non-existent (meta) 16-bit processor 
in software, interpreter style, which I call SWEET 16. 

SWEET 16 is based on sixteen 16-bit registers (R0-15), which 
are actually 32 memory locations. R0 doubles as the SWEET 16 
accumulator (ACC), R15 as the program counter (PC), and R14 
as the status register. R13 holds compare ins true t ion re- 
sults and R12 is the subroutine return stack pointer if SWEET 
16 subroutines are used* All other SWEET 16 registers are at 
the user's unrestricted disposal. 

SWEET 16 instructions fall into register and non-register 
categories. The register ops specify one of the sixteen 
registers to be used as either a data element or a pointer to 
data element or a pointer to data in memory, depending on the 
specific instruction. For example I NR R5 uses R5 as data and 
ST @R7 uses R7 as a pointer to data in memory. Except for 
the SET instruction, register ops take one byte of code each. 
The non-register ops are primarily 6502 style branches with 
the second byte specifying a +/-1 27 byte displacement rela- 
tive to the address of the following instruction. Providing 
that the prior register op result meets a specified branch 
condition, the displacement is added to the SWEET 16 PC, 
effecting a branch. 
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SWEET 16 is intended as a 6502 enhancement package , not a 
stand-alone processor* A 6502 program switches to SWEET 16 
mode with a subroutine call and subsequent code is inter- 
preted as SWEET 16 instructions* The nonregister op RTN 
returns the user program to 6502 mode after restoring the 
internal register contents (A, S , Y, P, and S), The fol- 
lowing example illustrates how to use SWEET 16. 


300 

B9 

00 

02 


LBA 

IN , Y 

get a char , 

303 

C9 

CD 



CMP 

# ff M” 

!, M n for move 

305 

D0 

09 



BNE 

NOMOVE 

No . skip move 

307 

20 

89 

F6 


JSR 

SW16 

Yes , call SWEET 16 

30A 

41 



ML00P 

LD 

0R1 

R1 holds source 

30B 

52 




ST 

0R2 

R2 holds dest . addr . 

30C 

F3 




DCR 

R3 

Deer . length 

30D 

07 

FB 



BNZ 

ML00P 

Loop until done 

30F 

00 




RTN 


Return to 6502 mode . 

310 

C9 

C5 


NOMOVE 

CMP 

#"E H 

,! E !! char? 

312 

D0 

13 



BEQ 

pytt 

.Li ■A .it i 

Yes , exit 

314 

C8 




I NY 


No, cont , 


NOTE: Registers A, X, Y, P, and S are not disturbed by SWEET 

16. 


11*2, Instruction Descriptions 

The SWEET 16 opcode list ing is short and uncomplicated. 
Excepting relative branch displacements, hand assembly is 
trivial. All register opcodes are formed by combining two 
Hex digits, one for the opcode and one to specify a register. 
For example , opcodes 15 and 45 both specify register R5 while 
codes 23, 27 and 29 are all ST ops. Most register ops are 
assigned in complementary pairs to facilitate remembering 
them. Therefore, LD and ST are opcodes 2N and 3N respec- 
tively, while LD 0 and ST 0 are codes 4N and 5N. 
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Opcodes 0 to C (Hex) are assigned to the thirteen non-regis- 
ter ops* Except for RTN (opcode 0 ) , BK (0A) , and RS (0B) , 
the non register ops are 6502 style branches* The second 
byte of a branch instruction contains a +/-127 byte displace- 
ment value (in two's complement form) relative to the address 
of the instruction immediately following the branch. 

If a specified branch condition is met by the prior register 
op result , the displacement is added to the PC effecting a 
branch. Except for BR (Branch always) and BS (Branch to 
Subroutine) , the branch opcodes are assigned in complementary 
pairs, rendering them easily remembered for hand coding. For 
example. Branch if Plus and Branch if Minus are opcodes 4 and 
5 while Branch if Zero and Branch if NonZero are opcodes 6 
and 7 • 


11.3. Sweet 16 Opcode Summary 


11.3.1. Register OPS 


In 

Cl? 
Oils 1 

Rn 

Constant ( Set ) 

2n 

LD 

Rn 

(Load) 

3n 

ST 

Rn 

(Store) 

4n 

LD 

@Rn 

(Load Indirect ) 

5n 

ST 

@Rn 

(Store Indirect) 

6n 

LDD 

@Rn 

(Load Double Indirect ) 

7n 

STD 

@Rn 

(Store Double Indirect ) 

8n 

POP 

@Rn 

(Pop Indirect) 

9n 

STP 

@Kn 

(Store POP Indirect ) 

An 

ADD 

Rn 

(Add) 

Bn 

SUB 

Rn 

(Sub) 

Cn 

POPD 

@Rn 

(Pop Double Indirect ) 

Dn 

CPR 

Rn 

(Compare) 

En 

I NR 

Rn 

( Increment ) 

Fn 

DCR 

Rn 

(Decrement ) 
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11*3.2. Non-register OPS 


00 

RTN 


(Return to 6502 mode) 

01 

BR 

ea 

(Branch always) 

02 

BNC 

ea 

(Branch if No Carry) 

03 

BC 

ea 

(Branch if Carry) 

04 

BP 

ea 

(Branch if Plus) 

05 

BM 

ea 

(Branch if Minus ) 

06 

BZ 

ea 

(Branch if Zero) 

07 

BNZ 

ea 

(Branch if NonZero) 

08 

BM1 

ea 

(Branch if Minus 1 ) 

09 

BNM1 

ea 

(Branch if Not Minus 1) 

0A 

BK 


(Break) 

0B 

RS 


(Return from Subroutine) 

0C 

BS 

ea 

(Branch to Subroutine) 

0D 



(Unassigned) 

0E 



(Unassigned) 

0F 



(Unassigned) 


11.4. Register Instructions 
11.4.1. SET 

SET Rn,Cons tant In Low High 

The 2-byte constant is loaded into Rn (n=0 to F, Hex) 
and branch conditions set accordingly. The carry is 
cleared . 

EXAMPLE : 

15 34 A0 SET R5 , $A034 R5 now contains $A034 
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11*4,2* LOAD 
LD Rn 2n 

The ACC (R0) is loaded from Rn and branch conditions set 
according to the data transferred. The carry is cleared 
and contents of Rn are not disturbed* 

EXAMPLE : 

15 34 A0SEI R5 , $A034 

25 LD R5 ACC now contains $A034 

11*4.3* STORE 
ST Rn 3n 

The ACC is stored into Rn and branch conditions set 
according to the data transferred* The carry is cleared 
and the ACC contents are not disturbed. 

EXAMPLE : 

25 LD R5 
36 ST R6 


11*4*4, LOAD INDIRECT 
LD @Rn 4n 

The low-order ACC byte is loaded from the memory loca- 
tion whose address resides in Rn and the high-order ACC 
byte is cleared. Branch conditions ref lect the final 
ACC contents which will always he positive and never 
minus 1 , The carry is cleared. After the transfer, Rn 
is incremented by 1, 


Copy the contents 
of R5 to R6 
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EXAMPLE : 

15 34 A0 SET R5 , $A034 

45 LD @R5 ACC is loaded from memory 

location $A034 
R5 is incr to $A035 

11*4*5, STORE INDIRECT 
ST ®Rn 5n 

The low-order ACC byte is stored into the memory loca- 
tion whose address resides in Rn. Branch conditions 
reflect the 2-byte ACC contents® The carry is cleared* 
After the transfer Rn is incremented by 1* 

EXAMPLE : 

15 34 A0 SET R5, $A034Load pointers R5, R6 with 

16 22 90 SET R6, $9022$A034 and $9022 

45 LD @R5 Move byte from $A034 to $9022 

56 ST 0R6 Both ptrs are incremented 

11*4,6, LOAD DOUBLE -BYTE INDIRECT 
LDD @Rn 6n 

The low order ACC byte is loaded from memory location 
whose address resides in Rn, and Rn is then incremented 
by 1, The high order ACC byte is loaded from the memory 
location whose address resides in the incremented Rn , 
and Rn is again incremented by 1, Branch conditions 
reflect the final ACC contents. The carry is cleared. 

EXAMPLE t 

15 34 A0 SET R5, $A034 The low-order ACC byte is loaded 
65 LDD @R6 from $A034, high-order from 

$A035, R5 is incr to $A036 
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11*4.7* STORE DOUBLE-BYTE INDIRECT 
STD @Rn 7n 

The low-order ACC byte is stored into memory location, 
whose address resides in Rn, and Rn is then incremented 
by 1. The high-order ACC byte is stored into the memory 
location whose address resides in the incremented Rn, 
and Rn is again incremented by 1 • Branch conditions 
reflect the ACC contents which are not disturbed. The 
carry is cleared* 

EXAMPLE : 

15 34 A0 SET R5, $A034 Load pointers R5, R6 

16 22 90 SET R6, $9022 with $A034 AND $9022 

65 LDD @R5 Move double byte from 

76 STD @R $A034-35 TO $9022-23, 

Both pointers incremented by 2. 


11*4.8. POP INDIRECT 
POP @Rn 8n 

The low-order ACC byte is loaded from the memory loca- 
tion whose address resides in Rn after Rn is decremented 
by 1 , and the high order ACC byte is cleared. Branch 
conditions reflect the final 2-byte ACC contents which 
will always be positive and never minus one. The carry 
is cleared. Because Rn is decremented prior to loading 
the ACC, single byte stacks may be implemented with the 
ST @Rn and POP @Rn ops (Rn is the stack pointer). 
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EXAMPLE : 

15 34 A0 SET R5, $A034 

10 04 00 SET R0, 4 

55 ST @R5 

10 05 00 SET R0, 5 

55 ST @R5 

10 06 00 SET R0 s 6 

55 ST (§R5 

85 POP @R5 

85 POP @R5 

85 POP @R5 


11,4*9, STORE POP INDIRECT 
STP @Rn 9n 

The low-order ACC byte is stored into the memory loca- 
tion whose address resides in Rn after Rn is decremented 
by 1, Branch conditions will reflect the 2-byte ACC 
contents which are not modified* STP @Rn and POP @Rn 
are used together to move data blocks beginning at the 
greatest address and working down* Additionally, 
single-byte stacks may be implemented with the STP @Rn 
ops. 

EXAMPLE : 


14 34 A0 SET R4 , $A034 Init pointers 

15 22 90 SET R5, $9022 


84 

POP @R4 

Move byte from 

95 

STP @R5 

$A033 to $9021 

84 

POP @R4 

Move byte from 

95 

STP @R5 

$A032 to $9020 


Init stack pointer 

Load 4 into ACC 

PUSH 4 onto stack 

Load 5 into ACC 

Push 5 onto stack 

Load 6 into ACC 

Push 6 onto stack 

Pop 6 off stack into ACC 

Pop 5 off stack 

Pop 4 off stack 
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11,4* 10, ADD 

ADD Rn An 

The contents of Rn are added to the contents of ACC (R) 
and the low-order 16 bits of the sum restored in ACC, 
The 17th sum bit becomes the carry and the other branch 
conditions ref lect the final ACC contents* 


EXAMPLE : 


10 

34 

76 

SET 

R0 , $7634 

Init 

R0 

( AC C ) 

and Rl 

11 

27 

42 

SET 

Rl, $4227 





A1 



ADD 

R1 

Add 

Rl 

(SUIIF 

-B85B c clear) 

A0 



ADD 

R0 

Double 

ACC 

(R0) 

to $70B6 


with carry set . 


11*4*11* SUBTRACT 
SUB Rn Bn 

The contents of Rn are Subtracted from the ACC contents 
by performing a two's complement addition: 

ACC = ACC + Rn + 1 

The low-order 16 bits of the subtraction are restored in 
the ACC, the 17th sum bit becomes the carry and other 
branch conditions reflect the final ACC contents* If 
the 16-bit unsigned ACC contents are greater than or 
equal to the 16-bit unsigned Rn contents, then the carry 
is set, otherwise it is cleared, Rn is not disturbed. 

EXAMPLE : 


10 

34 

76 

SET 

R0 , $7634 

Init R0 (ACC) 

11 

27 

42 

QT?rp 

Rl, $4227 

and Rl 

B1 



SUB 

Rl 

Subtract Rl 






(dif f=$340D with c set) 

B0 



SUB 

R0 

Clears ACC . (R0) 
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11*4*12, POP DOUBLE-BYTE INDIRECT 
POP @Rn Cn 

Rn is decremented by 1 and the high-order ACC byte is 
loaded from the memory location whose address now re- 
sides in Rn. Rn is again decremented by 1 and the low- 
order ACC byte is loaded from the corresponding memory 
location. Branch conditions reflect the final ACC con- 
tents . 

The carry is cleared. Because Rn is decremented prior 
to loading each of the ACC halves, double-byte stacks 
may be implemented with the STD @Rn and POPD @Rn ops (Rn 
is the stack pointer), 

EXAMPLE : 

15 34 A0 SET R5 , $A034 Ini t stack pointer 

10 12 AA SET R0 S $AA12 Load $AA12 into ACC . 

75 STD 0R5 Push $AA12 onto stack 

10 34 BB SET R0, $BB34 Load $BB34 into ACC • 

75 STD @R5 Push $BB34 onto stack 

C5 POPD @R5 Pop $BB34 off stack 

C5 POPD 0R5 Pop $AA12 off stacy 


11*4*13® COMPARE 
CPR Rn Dn 

The ACC (R0) contents are compared to Rn by performing 
the 16-bit binary subtraction ACC-Rn and storing the low 
order 16 difference bits in R13 for subsequent branch 
tests. If the 16-bit unsigned ACC contents are greater 
than or equal to the 16-bit unsigned Rn contents, then 
the carry is set, otherwise it is cleared. No other 
registers, including ACC and Rn are disturbed. 
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EXAMPLE : 




15 

34 A0 

SET R5, $A034 

Pointer to memory 

16 

BF A0 

SET R6, $A0BF 

Limit address 


B0 


L00P1 SUB R0 

Zero data 


75 


STD @R5 

Clear 2 locns 





Increment R5 by 

2 

25 


LD R5 

Compare pointer 

R5 

D6 


CPR R6 

to limit R6 


02 

FA 

BNC L00P1 

Loop if c clear 


1 1 « 4 » 1 4 

. INCREMENT 




INR Rn En 

The contents of Rn are incremented by 1* The carry is 
cleared and other branch conditions reflect the incre- 
mented value, 

EXAMPLE : 


$A034 (Pointer) 

Zero to R0 
Clr Locn $A034 
Incr R5 to $A036 
Glrs locn $A036 
(not $A035) 

11,4.15, DECREMENT 
DCR Rn Fn 

The contents of Rn are decremented by 1. The carry is 
cleared and other branch conditions reflect the decre- 
mented value. 


15 34 A0 

cpT "R S 

B0 

SUB R0 

55 

ST @R5 

E5 

INR R5 

55 

ST @R5 
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EXAMPLE : 

(Clear 9 

bytes 

15 

34 A0 

SET 

R5 , 

$A034 

14 

09 00 

SET 

R4, 

9 

B0 


SUB 

R0 


55 


L00P2 ST 

@R5 

F4 


OCR 

R4 


07 

FC 

BNZ 

L00P2 


beginning at location A034) 

Init Pointer 
In it counter 
Zero ACC 

Clear a mem byte 
Decrement count 
Loop until Zero 


11.5, Non-Register Instructions 


11.5.1. RETURN TO 6502 MODE 
RTN 00 

Control is returned to the 6502 and program execution 
continues at the location immediately following the RTN 
instruction. The 6502 registers and status conditions 
are restored to their original contents (prior to en- 
tering SWEET 16 mode)* 


11*5*2, BRANCH ALWAYS 
BR ea 01 d 

An effective address (ea) is calculated by adding the 
signed displacement byte (d) to the PC* The PC contains 
the address of the instruction immediately following the 
BR, or the address of the BR op plus 2, The displace- 
ment is a signed two's complement value from -128 to 
+127, Branch conditions are not changed. 
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NOTE; The effective address calculation is identical to 
that for 6502 relative branches. The Hex add & subtract 
features of the APPLE ] [ monitor may be used to calcu- 
late displacements. 


d 

= 

$80 

ea 

= PC 

+ 

2 

— 

128 

d 

= 

$81 

ea 

= PC 


2 

— 

127 

d 

— 

$FF 

ea 

= PC 

4- 

2 

_ 

1 

d 

= 

$00 

ea 

= PC 


2 

+ 

0 

d 


$01 

ea 

= PC 

+ 

2 

+ 

1 

d 

= 

$7E 

ea 

= PC 

+ 

2 

+ 

126 

d 

= 

$7F 

ea 

o 

it 

"P 

2 

+ 

127 


EXAMPLE : 

$300; 01 50 BR $352 

11.5.3. BRANCH IF NO CARRY 
BNC ea 02 d 


A branch to the effective address is taken only if the 
carry is clear, otherwise execution resumes as normal 
with the next instruction. Branch conditions are not 
changed . 


11.5.4. BRANCH IF CARRY SET 
BC ea 03 d 

A branch is effected only if the carry is set. Branch 
conditions are not changed. 


119 



MERLIN Users Menus! 


SWEET 16 


11.5,5, BRANCH IF PLUS 


BP ea 04 d 


A branch is effected only if the prior 'result 7 (or most 
recently transferred data) was positive* Branch condi- 
tions are not changed* 


EXAMPLE : (Clear mem from A034 to A03F) 


15 34 A0 
14 3F A0 
B0 
55 

24 

D5 

04 FA 


SET R5 , $A034 Init pointer 
SET R4 , $A03F Init limit 
LOOP 3 SUB R0 

ST @R5 Clear mem byte 
; Increment R5 
LD R4 Compare limit 
CPR R5 to pointer 
BP L00P3 Loop until done 


11,5.6* BRANCH IF MINUS 
BM ea 05 d 

A branch is effected only if prior 'result' was minus 
(negative, MSB = 1), Branch conditions are not changed. 


11.5.7. BRANCH IF ZERO 
BZ ea 06 d 

A branch is effected only if the prior 'result' was 
zero- Branch conditions are not changed. 
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11*5.8, BRANCH IF NONZERO 
BNZ ea 07 d 

A branch is effected only if the prior 'result' was non- 
zero, Branch conditions are not changed. 


11,5,9, BRANCH IF MINUS ONE 

BM1 ea 08 d 

A branch is effected only if the prior 'result' was 
minus one ($FFFF Hex), Branch conditions are not 
changed. 


11,5,10, BRANCH IF NOT MINUS ONE 
BNM 1 ea 09 d 

A branch is effected only if the prior 'result' was not 
minus 1, Branch conditions are not changed. 


11,5,11, BREAK 
BK 0A 

A 6502 BRK (break) instruction is executed, SWEET 16 
may be re-entered non destructively at SW 16d after cor- 
recting the stack pointer to its value prior to ex- 
ecuting the BRK. 
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11.5. 12* RETURN FROM SWEET 16 SUBROUTINE 
RS 0B 

RS terminates execution of a SWEET 16 subroutine and 
returns to the SWEET 16 calling program which resumes 
execution (in SWEET 16 mode)* R1 2 , which is the SWEET 
16 subroutine return stack pointer, is decremented 
twice* Branch conditions are not changed* 


11,5,13. BRANCH TO SWEET 16 SUBROUTINE 
BS ea 0C d 

A branch to the effective address (PC + 2 + d) is taken 
and execution is resumed in SWEET 16 mode. The current 
PC is pushed onto a 'SWEET 16 subroutine return address' 
stack whose pointer is R12, and R12 is incremented by 2* 
The carry is cleared and branch conditions set to indi- 
cate the current ACC contents. 

EXAMPLE? (Calling a 'memory move' subroutine to move 
A034-A03B to 3000-3007) 


15 

34 

A0 

SET 

R5, $A034 

Init 

pointer 

1 

1 4 

3B 

A0 

SET 

R4, $A03B 

Init 

limit 1 


16 

00 

30 

SET 

R6 , $3000 

Init 

pointer 

2 

0C 

15 


BS 

MOVE 

Call 

move subrtn 

45 

MOVE 

LD 

@R5 

Move 

one 


56 



ST 

@R6 

byte 



24 



LD 

R4 




D5 



CPR 

R5 

Test 

if done 


04 

FA 


BP 

MOVE 




0B 



RS 


; Re turn 
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11,6. Theory of Operation 

SWEET 16 execution mode begins with a subroutine call to 
SW 16. All 6502 registers are saved at this time, to be 
restored when a SWEET 16 RTN instruction returns control to 
the 6502, If you can tolerate indefinite 6502 register 
contents upon exit, approximately 30 usee may be saved by 
entering at SW 16 + 3. Because this might cause an inadver- 
tent switch from Hex to Decimal mode , it is advisable to 
enter at SW16 the first time through. 

After saving the 6502 registers, SWEET 16 initializes its PC 
(R15) with the subroutine return address off the 6502 stack. 
SWEET 16's PC points to the location preceding the next 
instruction to be executed. Following the subroutine call 
are 1-, 2~, and 3-byte SWEET 16 instructions , stored in 
ascending memory locations like 6502 instructions. The main 
loop at SW 1 6B repeatedly calls the 'execute instruction' 
routine to execute it. 

Subroutine SW16C increments the PC (R15) and fetches the next 
opcode, which is either a register op of the form OP REG with 
OP between 1 and 1 5 or a. non-register op of the form 0 OP 
with OP between 0 and 13. Assuming a register op, the regis- 
ter specification is doubled to account for the 3 byte SWEET 
16 registers and placed in the X-reg for indexing. Then the 
instruction type is determined. Register ops place the 
doubled register specification in the high order byte of R 14 
indicating the 'prior result register' to subsequent branch 
instructions. Non-register ops treat the register specifica- 
tion (right-hand half-byte) as their opcode, increment the 
SWEET 16 PC to point at the displacement byte of branch 
instructions, load the A-reg with the 'prior result register' 
index for branch condition testing, and clear the Y-reg. 
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11*7, When is an RTS really a JSR? 

Each instruction type has a corresponding subroutine. The 
subroutine entry points are stored in a table which is direc- 
tly indexed into by the opcode. By assigning all the entries 
to a common page, only a single byte of address need be 
stored per routine. The 6502 indirect jump might have been 
used as follows to transfer control to the appropriate sub- 
routine • 

LDA #ADRH 

STA IND+1 

LDA OPTBL , X 

STA IND 

JMP (IND) 

To save code, the subroutine entry address (minus 1) is 
pushed onto the stack, high -order byte first. A 6502 RTS 
(return from subroutine) is used to pop the address off the 
stack and into the 6502 PC (after incrementing by 1). The 
net result is that the desired subroutine is reached by 
executing a subroutine return instruction! 


High-order byte. 
Low-order byte. 


11*8. OPcode Subroutines 

The register op routines make use of the 6502 "zero page 
indexed by X" and "indexed by X indirect" addressing modes to 
access the specified registers and indirect data. The "re- 
sult" of most register ops is left in the specified register 
and can be sensed by subsequent branch instructions, since 
the register specification is saved in the high-order byte of 
R14. This specification is changed to indicate R0 (ACC) for 
ADD and SUB instructions and R13 for the CPR (compare) in- 
struction. 

Normally the high-order R14 byte holds the "prior result 
register" index times 2 to account for the 2-byte SWEET 16 
registers and the LSB is zero. If ADD, SUB, or CPR instruc- 
tions generate carries, then this index is incremented, set- 
ting the LSB, 
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11.10, User Modifications 

You may wish to add some of your own instruction to this 
implementation of SWEET 16* If you use the unassigned op- 
codes $0E and $0F, remember that SWEET 16 treats these as 2- 
byte instructions. You may wish to handle the break instruc- 
tion as a SWEET 16 call, saving two bytes of code each time 
you transfer into SWEET 16 mode. Or you may wish to use the 
SWEET 16 BK (break) op as a 'CHAROUT' call in the interrupt 
handler. You can perform absolute jumps within SWEET 16 by 
loading the ACC (R0) with the address you wish to jump to 
(minus 1) and executing a ST R15 instruction. 
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12* APPLESOFT LISTING INFORMATION 


12.1. SOURCEROR.FP 

A fully labelled and commented source listing of Applesoft 
BASIC can be generated by the program, SOURCEROR.FP on the 
opposite side of the MERLIN diskette. 

This program works by scanning the resident copy of Applesoft 
present in your computer and by generating text files con- 
taining the bulk of Applesoft BASIC: T.APSOFT I, T.APSOFT II, 
T.APSOFT III and T.APSOFT IV (the 48K version uses T.APSOFT 1 
through T.APSOFT 7 instead)* 

To conserve space, these files contain macros that are de- 
fined in another file on the disk entitled, APPLESOFT. S. 
This file, when assembled using the PRTR command, will print 
out a nicely formatted disassembly of Applesoft, auto- 
matically bringing in and using the AP SOFT files as 
necessary. Exact details on doing this are outlined below. 

PLEASE NOTE that this is NOT an "official 11 source listing 
from Apple Computer, Inc., but rather a product of the 
Author's own research and interpretation of the original 
Applesoft ROM. Apple Computer, Inc. was not in any way 
involved in the preparation of this data, nor was the final 
product reviewed for accuracy by that company. Use of the 
term APPLE should not be construed to represent any endorse- 
ment, official or otherwise, by Apple Computer, Inc* 

Additionally, Southwestern Data Systems makes no warranties 
concerning the accuracy or usability of this data. It is 
provided solely for the entertainment of users of the MERLIN 
assembler . 
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13* GLOSSARY 


ABORT 

ACCESS 



ALLOCATE 


BIMARY 

BIT 



BUFFER. 


CARRY 

CHIP 


CODE 


-terminate an operation prematurely, 
-locate or retrieve data. 

-a memory location. 

-a method of solving a specific problem. 

-set aside or reserve space, 

-industry standard system of 128 computer 
codes assigned to specified alpha-numeric 
and special characters, 

-in number systems, the exponent at which 
the system repeats itself; the number of 
symbols required by that number system. 

-the base two number system , composed 
solely of the numbers zero and one. 

-one unit of binary data, either a zero or 
a one. 

-resume execution at a new location. 

-large temporary data storage area , 

-Hex representation of eight binary bits. 

-flag in the 6502 status register. 

-tiny piece of silicon or germanium con- 
taining many integrated circuits. 

-slang for data or machine language in- 
structions . 
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SIGN BIT 
SOURCE CODE 

STACK 

STRING 

SWEET 16 

SYMBOL 

SYNTAX 

TABLE 

HIGGLE 

VARIABLE 

VECTOR 


--bit seven of a byte; negative if value 
greater than $80* 

-“data entered into an assembler which will 
produce a. machine language program when 
assembled • 

-temporary storage area in RAM used by the 
6502 and assembly language programs, 

-a group of ASCII characters usually en- 
closed by delimiters such as ' or ", 

-program which simulates a 16 bit micro- 
processor « 

-symbolic or mnemonic label . 

-prescribed method of data entry • 

-list of values , words, data referenced by 
a program, 

-switch from one state to the other . 

-alpha-numeric expression which may assume 
or be assigned a number of values, 

-address to be referenced or branched to. 
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14. SAMPLE PROGRAMS 


The first group of three programs are superb Assembly Lan- 
guage utilities written by Steve Wozniak and Allen Baum, and 
are still found on the original Integer Basic F4 ROM. They 
are Supplied in source code format on this diskette for the 
benefit of Apple ] [ Plus owners who do not have Integer 
Basic, They may be located at any convenient memory 

location » 


14.1. The Floating Point Routines 

These are single precision floating point routines that may 
be interfaced to a BASIC or assembly language program. In- 
formation on their use may be found in the source listings 
themselves » 


14.2, The Multiply /Divide Routines 

These routines are intended to be used as subroutines in 
assembly language programs providing a four byte multiply or 
divide result. Brief information on their use is provided in 
the source listings , and a multiply demo by Dave Garson is 
included on this diskette. 


14,3. PRDEC 

This is one the most used subroutines in the Integer Basic 
ROM set. It is called by virtually every routine which re- 
quires the output of an integer number in the range 0-65535. 
It is easily integrated in any Assembly Language program. To 
use it j load the accumulator with the high-order byte of 
[number ] , load X with the low— byte and call PRDEC, Alter- 
natively, store the high-byte in $F3 ? the low byte in $F2 9 
and call PRDEC+4. 
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1 4.4. MSGOUT 

This is a subroutine by Andy Hertzfeld to output ASCII 
strings from an Assembly Language program. If MERLIN INV or 
FLS Pseudo-ops are used in connection with it, the ORA #$80 
must be removed, and all normal ASCII must have the high-bit 
set. .Also in the same source file are two simple subroutines 
to read ASCII and hexadecimal characters input by the user* 


14.5. UPCON 

This utility by Glen Bredon is provided for users who do not 
have a lowercase video display chip. It will search for 
source file comments beginning with either n * !l or "j"* and 
convert all lower case characters to upper case* Load the 
source file with MERLIN, then BRUN UPCON, via the 'C' command 
in. the EXEC mode. 


14.6. Game Paddle Printer Driver 

When the Apple ] [ was first developed, there were no printer 
interface cards, nor was there really much consideration even 
given to the need for a printer. Obviously, the folks at 
Apple computer had a requirement to hard copy their develop- 
ment routines, thus a primitive, teletype driver was written 
by Randy Wigging ton and Steve Wozniak to serve their in-house 
needs* This was subsequently published in the famous "red 
book" instruction manual, the second for the Apple ] [. Along 
came the Disk ]{, and lo and behold, the driver would not 
work, since it ignored DOS and set its own I/O hooks. Next 
the Aldrich brothers took care of this problem, and we were 
back in business* By this time, of course, there was no 
desperate need for a game paddle driver; interface cards were 
developed, and worked well. Nevertheless, some users con- 
tinued using the game 1/0 driver, so Dave Garson and Val 
Golding again modified the drive so that inverse and flashing 
characters would not upset the printer when doing a catalog, 
etc , 
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Concurrently, many new interface cards of all kinds were 
developed for the Apple; clock cards, 80 column cards, ROM 
cards, etc*, until card space is now at a premium* Running a 
serial printer from the game I/O port is one way in which the 
user can save both the cost of a printer interface and the 
slot space it would occupy* Already the teletype driver has 
been adapted to such printers as Integral Data, Base 2, Heath 
H-14, and others* 

As a last step, Glen Bredon has added a number of improve- 
ments to the driver* It can print formatted BASIC listings 
to any column width, starting with column one, can be output 
with or without video. The video may be left on even when 
printing beyond 40 columns , something most interface cards 
can not do* " These functions are handled by Basic POKE state- 
ments to the flags at the end of the program. 

Full documentation and instructions are contained in the 
source file included on this diskette* Naturally, it is 
completely compatible with MERLIN, and called witn the MERLIN 
USER command* This is set up when it is first BRUN, which 
establishes the ampersand hooks, which may also be used from 
BASIC* 

In addition, the source code is well commented, so that it in 
itself, serves as a tutorial on writing driver routines for 
different applications, etc* 
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15. UTILITIES 


15.1, Formatter 

This program is provided to enhance the use of MERLIN as a 
general text editor* It will automatically format a file 
into paragraphs using a specified line length. Paragraphs 
are separated by empty lines in the original file. 

To use FORMATTER, you should first BRUN it from EXEC mode. 
FORMATTER loads itself $9064 and relocates itself to $94A0. 
This will simply set up the editor's USER vector. To format 
a file which is in memory, issue the USER command from the 
editor . 

The formatter program will request a range to format. If you 
just specify one number, the file will be formatted from that 
line to the end. Then you will be asked for a line length, 
which must be less than 250, Finally, you may specify 
whe ther you want the file justified on both sides (rather 
than just on the left). 

The first thing done by the program is to check whether or 
not each line of the file starts with a space. If not, a 
space is inserted at the start of each line. This is to be 
used to give a left margin using the editor's TAB command 
before using the PRINT command to print out the file. 

Formatter uses inverse spaces for the fill required by two- 
sided justification. This is done so that they can be lo- 
cated and removed if you want to reformat the file later. It 
is important that you do not use the FIX or TEXT commands on 
a file after it has been formatted (unless another copy has 
been saved). For files coming from external sources, it is 
desirable to first use the FIX command on them to make sure 
they have the form expected by FORMATTER. For the same 
reason, it is advisable to reformat a file using only left 
justification prior to any edit of the file. 
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Don't forget to use the TABS command before printing out a 
formatted file* 

15*2* CHRGEN 70 

CHRGEN 70 is a 70-column character generator which Is de- 
signed specifically to allow the use of MERLIN with a 70 
column by 24 line display on the Hi-Res screen* Because of 
the large amount of memory required, CHRGEN 70 is available 
only with the RAM card version of MERLIN. 

TV sets do not provide sufficient resolution for use with 
CHRGEN 70, thus requiring use of a display monitor for 
satisfactory results. 

To use CHRGEN 70, you must first BRUN it from MERLIN's EXEC 
mode as a DOS command (after a CATALOG). This will reset the 
source address to $4001 (above the Hi-Res screen which must 
be used by CHRGEN 70). This , of course , will delete any 
source file in memory at the time. Once it has been BRUN, 
you can invoke it at any time by typing "USER" f rom the 
editor . 

To exit CHRGEN 70, simply type VXD 0, VXD 16, or PR#0 from 
the editor. CHRGEN 70 is automatically disconnected when you 
exit the editor to the EXEC Mode. Upon return to the editor, 
you can reconnect it by typing "USER" again. To permanently 
remove CHRGEN 70 in order to free up the area normally used 
by long source listings, you will have to BRUN MERLIN again. 

To use CHRGEN 70 with the editor's PRTR command, just type 
PRTR 8 "filename", with CHRGEN 70 installed in the system. 

If the USER vector has been written over by some o the r USER 
routine, it can be reset to point to CHRGEN 70 either by 
BRUNing CHRGEN 70 again, or by going to the Monitor (use the 
MON command) and typing in 900G. The latter assumes , of 
course, that CHRGEN 70 is still intact at $900. 
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As you can see from the above example (taken from the SWEET 
1 6 source file on the MERLIN diskette), the "definition 11 or 
actual value of the label is indicated by the sign, and 
the line number of each line in the source file that the 
label appears in is listed to the right of the definition. 
In addition, the line numbe r where the label is either de- 
fined or used as a major entry point is suffixed ("flagged") 
with a 

An added feature is a special notation for additional source 
files that are brought in during assembly with the PUT pseudo 
opcode : "1 34.82", for example , indicates line number 134 of 
the main source file (which will be the line containing the 
PUT opcode) and line number 8 2 of the PUT file, where the 
label is actually used. 


15,3.3. XREF Instructions 

1 . Get into MERLIN's Executive Mode, make sure you've S)aved 
the file that you're working on and select the D)rive no. 
that the MERLIN disk is in. 

2 . C)atalog the disk and when MERLIN asks you for a COMMAND: 

after the Catalog, enter: BRUN XREF. (Your file in 

memory will now be erased.) 

3. Hit <CTRL C> <RETURN> and re-L)oad your file. Initialize 
your printer with the appropriate PR# or PRTR command 
(XREF is a printer oriented command). 

4. Type in the appropriate USER command : 

USER 0 -Print assembly li s ting and alphabetical cross 
reference only. (USER has the same effect as 
USER 0). 

USER 1 -Print assembly listing and both alphabetical and 
numerically sorted cross reference listings. 

USER 2 -Do not print assembly listing but print alpha- 
betical cross reference only. 
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USER 3 -Do not print assembly listing but print both 
alphabetical and numerical cross reference 
listings * 

USER, commands 0-3 (above) cause labels within conditional 
assembly areas with the DO condition OFF to be ignored and 
not printed in the cross reference table* 

There are additional USER commands (4-7) that function the 
same as USER 0-3, except that they cause labels within con- 
ditional assembly areas to be printed no matter what the 
state of the DO setting is® The only exception to this is 
that labels defined in such areas and not elsewhere will be 
ignored , 

NOTE : You may change the USER command as many times as you 
wish (e.g, , from USER 1 to USER 2). The change is not per- 
manent until you enter the ASM command (below), 

5, Enter the ASM command to begin the assembly and printing 
process * 


15*3,4, CAUTIONS for the use of XREF 

XREF works by examining the listing output of the assembler* 
On the second assembly pass , it builds a cross reference list 
beginning at HIMEM ins tead of_ creating object code there, 
(If direct assembly to disk is selected by the DSK opcode , 
however, the object code w ill be generated). The list uses 
six bytes per symbol reference which can use up available 
memory very quickly. Thus , on long files, you should set 
HIMEM as low as possible, (The W0 command can be used to 
find the end of the source file, which represents the lowest 
position you can set HIMEM), 
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Since the program requires assembler output , code in areas 
with LST OFF will not be processed and labels in those areas 
will not appear in the table. In particular, it is essential 
to the proper working of XREF that the LST condition be ON at 
the end of assembly (since the program also intercepts the 
regular symbol table output). For the same reason, the CTRL 
D flush command must not be used during assembly. The pro- 
gram attempts to determine when the assembler is sending it 
an error message on the first pass and it aborts assembly in 
this case, but this is not 100% reliable. 

Macros require special consideration. Since the syntax in 
these structures can become very complicated , XREF may get 
confused and cause assembly to stop. This usually happens 
when lines containing the >>> (PMC or n Put MaCro) pseudo 
opcode are followed by string literals or parentheses and you 
have chosen to suppress printing the expanded form of the 
macro in your assembled listing with the EXP OFF pseudo 
opcode. You can get around this problem by printing out the 
assembly listing first in the usual manner (with the symbol 
table suppressed by the LST OFF pseudo opcode) and then 
printing out just the cross reference table with EXP ON and 
using USER 2 or 3, 

Another thing to look out for when using macros is the fact 
that labels defined withi n macro definitions have no global 
meaning and are therefore not cross-referenced. 

MAC < Macro definition 

CMP # ] 1 
BNE DONE 
ASL 
«< 

<— - Beg, of program 
>» DEF • GLOBAL < Macro call 

in the above example, variable GLOBAL will be. cross ref- 
erenced, but local label DONE will not. 


DEF 


DONE 
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15.3*5* XREF * XL Instructions 

XREF.XL is designed to handle files three to four times as 
large as those handled by XREF* It was originally designed 
to cross reference the Applesoft Basic source file, which is 
approximately the largest source file it can process* 

To use XREF.XL, just follow the same five steps in the XREF 
instructions explained previously, substituting H XREF.XL” for 
,f XREF” in step 2. 

XREF.XL works in a manner similar to XREF, except that it 
writes the cross reference label table to disk in a file 
called X.R.FILE (You can delete this file when you are done 
with the table). At the end of assembly, this file is loaded 
from disk and placed in memory, overwriting your source file* 
As explained in step 1, make sure that you've saved your 
source file first, because the source file will be deleted 
from memory when you return to the editor. 


15*3,6. CAUTIONS for the use of XREF.XL 

-The source file will be deleted from memory as explained 
above when you return to the editor. Make sure that you 
have saved your file first. 

-Consider using a blank disk when using XREF.XL. The disk 
file generated, X.R.FILE, can become quite large. 

-The cross reference label table X.R.FILE is written on the 
disk in the disk drive last used. If your source file 
contains PUT directives, you will have to make sure XREF.XL 
can find the additional source files by either moving the 
files onto the blank disk or by specifying drive and slot 
parameters in the PUT directive. 
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Unlike XREF, the setting of HIMEM does not affect XREF* XL. 
While building the cross reference table, XREF. XL checks to 
see if it will fit in the space from the source address 
(approximately) to the SYM address , if specified, or to 
$9853 if not* If it is too large, XREF.XL will quit with an 
OUT OF MEMORY message. 

XREF.XL will quit with an ILLEGAL DSK ATTEMPTED error 
message if it finds a DSK pseudo op code in your source 
file. A handy way of avoiding this problem while at the 
same time maintaining the same line numbers in the source 
file is to use the editor to change any DSK directives into 

comments * 


Special Instructions for Cross Referencing the Apple so f t 

Source File : 

1. Use STRIP on all the Applesoft files and save them on a 
blank disk. 

2. In the file APPLESOFT. S (after stripping it) change the 
line EXP OFF to EXP ON (or just delete it). 

3. Delete the lines containing the SAVOBJ KBD directives and 
the DO-FIN segment containing the DSK opcode. While this 
is not necessary, it does avoid having SAVOBJ put in the 
symbol table. 

4. Make sure the last used drive (as shown in the EXEC menu) 
is the one containing the disk with the stripped files. 

5* Enter the desired PRTR command, and then USER 2 or USER 3. 

6* Enter ASM and be prepared for a cross reference table 
approximately 25 pages long. 
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15*4. STRIP 

Very long source files , or ones that contain numerous com- 
ments j may require too much memory for the cross reference 
table to be generated* In this case, assembly will stop with 
the OUT OF MEMORY error message* 

The utility program STRIP allows you to cross reference files 
approximately twice as large by removing comments from the 
source file. 

To use STRIP, follow the following procedure : 

1 . Make sure that you have a copy of your commented source 
file in memory and that you have S)aved a copy of it on 

l^TT ^ 

2* Enter the E)ditor , put a LST OFF at the end of your source 
file and ASM it. 

3* Remove the LST OFF statement at the end of your program 
(important ! ) » 

4 . Q)uit the editor, select the D)rive with MERLIN in it and 
do a C)atalog. At the COMMAND: prompt , enter: BRUN STRIP. 
This will remove the comments from your source file in 
memory • 

5 . Hit <CTRL C> <RETURN> and enter the E)ditor. You may now 
use the XREF and XREF.XL procedures as outlined above. 


15.5. PRINTFILER 

PRINTFILER is a utility included on the MERLIN diskette that 
saves an assembled listing to disk as a sequential disk 
file. It optionally allows you to also select ’’file 
packing” for smaller space requirements and allows you to 
turn video output off for faster operation. 
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Text files generated by PRINTFILER include the object code 
portion of a disassembled listing , something not normally 
available when saving a source file. This allows a complete 
display of an assembly language program and provides the 
convenience of not having to assemble the program to see what 
the object code looks like. 


15.5.1. Applications 

Applications include : 

-Incorporating the assembled text file in a document being 
prepared by a word processor. 

-Sending the file over a telephone line using a modem. 

-Mailing the file to someone who wants to work with the 
complete disassembly without having to assemble the program 
(such as magazine editors , etc.) 


15.5.2. How To Use PRINTFILER 

1 . From EXEC mode , make sure that you've S)aved any source 
file that you may be working on (select the D)rive to save 
it on, first) , select the D)rive containing PRINTFILER 
(usually this is on the MERLIN disk) and do a C)atalog. 
When you see the ’’COMMAND prompt, enter; BRUN 
PRINTFILER, (You may skip this step if you've already 
BRUN PRINTFILER), 

2. Press < RE TURN > , select the D)rive containing the file you 
want to assemble and L)oad the file into memory. (You may 
skip this step if you've already BRUN PRINTFILER). 
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3* Q)uit the editor, select the D)rive that you want to save 
the assembly to , enter the E)di tor again and enter* USER 
"your file name 15 (include the quotes)*. Be aware that if 
you later intend to R)ead this file using MERLIN's text 
file reader , you will have to put a ”T.” in front of the 
filename in the USER command above; e.g., ”T. DUMMY” 

instead of “DUMMY”. Also, you may use a PRTR command 
instead of USER, if you wish; e.g. , PRTR 9 ”T.DUMMY”THIS 
IS A PAGE HEADER" 

4* Enter: ASM and after asking whether you want to "UPDATE 
SOURCE”, PRINTFILER will automatically assemble the source 
file directly to disk. Note that you will not see any- 
thing on your video screen because PRINTFILER is precon- 
figured to operate with the video output turned off for 
faster operation. 


15.5.3. Changing PRINTFILER 's Options 

PRINTFILER has two options that you may change: file packing 
and video output ("echoing”)* In addition, you can make the 
change temporary or permanent. 

File packing reduces the size of the text file saved to disk 
by replacing blanks from the source file with a single char- 
acter with its high bit turned off. A listing of a packed 
file will display the packed blank characters as an inverse 
letter, (inverse A= 1 blank, inverse R=2 blanks, inverse C=3 
blanks , etc.) 

Unpacking means restoring the text file to its original 
appearance. Note that while you cannot ASM (assemble) such a 
file, you can at least read it. Packed files are primarily 
intended for use with another 3DS product, "DOUBLETIME 
PRINTER”, which unpacks the file and "spools" it from disk to 
the printer* 

Video "echoing” means printing on the screen, what is sent to 
the disk. The time it takes to do this can slow PRINTFILER 
down® (See benchmarking results, next.) 
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1 5 * 5 * 4 * Benchmarking PRINTFILER 

Source File: SWEET 16. S (21 sectors) 

it je it is $c , k'kic'& 'kit •k'k'k it & it if 'k'k'te 

* File Type: Video : Sectrs : Time * 

* Unpacked : Video on : 61 : 59 * 

* Unpacked : Video off: 61 : 44 * 

* Packed : Video on : 38 : 42 * 

* Packed : Video off: 38 : 30 * 

'k^^'k'k'k'k'k'k'k'k'kis’k-k'k’k’k^'k’k'k'k'k^-kis'kick'k'k'k'k'k'k'k 


As you can see from the above, turning off video output makes 
PRINTFILER run approximately 25% faster. Additional speed 
can be gained by using packed files. 

In addition, unpacked files are nearly twice as large as 
packed files and nearly three times the size of the original 
source file* 


15.5,5. Changing PRINTFILER options 


To Change PRINTFILER options (temporarily) 
Get into the E)di tor , enter: MON and enter: 


300:00 00 
300:00 80 
300:80 00 
300:80 80 


for packed, video off , or. 
for packed, video on, or 
for unpacked, video off , or 
for unpacked, video on, or 


(normal values are 300:80 00 (unpacked, video off)) 

Hit <REIURN> <CTRL Y> <RETURN> to return to EXEC mode. The 
values you select will stay in effect until you BRUN 
PRINTFILER. again. 
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To Change PRINTFILER options (permanently) 

1* L)oad PRINTFILER and ASM it. During assembly, it will ask 
you the following questions in the steps below: 

2. After the UPDATE SOURCE? question, PRINTFILER will ask, 
"GIVE VALUE FOR FORMAT:”. If you hit " 0 ", you will turn 
the Pack option ON, If you hit ”1”, you will turn the 
Pack option OFF, 

3. PRINTFILER will then ask, ?f GIVE VALUE FOR MONITOR”. If 
you hit ,! 0", video output will be turned OFF. If you hi t 
"1 ! \ video output will be turned ON. PRINTFILER will then 
immediately assemble into object code. 

4. Q)uit the editor and save the G)hject code. Any time you 
BRUN this object code , it will use the values you put in 
it in steps 2 and 3 above. Thus , it is possible to use 
different versions of PRINTFILER instead of set ting 
options • 
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